message.h revision fbaaef999ba563838ebd00874ed8a1c01fbf286d
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#if defined(_WIN32) && defined(GetMessage) 127// windows.h defines GetMessage() as a macro. Let's re-define it as an inline 128// function. This is necessary because Reflection has a method called 129// GetMessage() which we don't want overridden. The inline function should be 130// equivalent for C++ users. 131inline BOOL GetMessage_Win32( 132 LPMSG lpMsg, HWND hWnd, 133 UINT wMsgFilterMin, UINT wMsgFilterMax) { 134 return GetMessage(lpMsg, hWnd, wMsgFilterMin, wMsgFilterMax); 135} 136#undef GetMessage 137inline BOOL GetMessage( 138 LPMSG lpMsg, HWND hWnd, 139 UINT wMsgFilterMin, UINT wMsgFilterMax) { 140 return GetMessage_Win32(lpMsg, hWnd, wMsgFilterMin, wMsgFilterMax); 141} 142#endif 143 144 145namespace google { 146namespace protobuf { 147 148// Defined in this file. 149class Message; 150class Reflection; 151 152// Defined in other files. 153class Descriptor; // descriptor.h 154class FieldDescriptor; // descriptor.h 155class EnumDescriptor; // descriptor.h 156class EnumValueDescriptor; // descriptor.h 157namespace io { 158 class ZeroCopyInputStream; // zero_copy_stream.h 159 class ZeroCopyOutputStream; // zero_copy_stream.h 160 class CodedInputStream; // coded_stream.h 161 class CodedOutputStream; // coded_stream.h 162} 163class UnknownFieldSet; // unknown_field_set.h 164 165// A container to hold message metadata. 166struct Metadata { 167 const Descriptor* descriptor; 168 const Reflection* reflection; 169}; 170 171// Returns the EnumDescriptor for enum type E, which must be a 172// proto-declared enum type. Code generated by the protocol compiler 173// will include specializations of this template for each enum type declared. 174template <typename E> 175const EnumDescriptor* GetEnumDescriptor(); 176 177// Abstract interface for protocol messages. 178// 179// See also MessageLite, which contains most every-day operations. Message 180// adds descriptors and reflection on top of that. 181// 182// The methods of this class that are virtual but not pure-virtual have 183// default implementations based on reflection. Message classes which are 184// optimized for speed will want to override these with faster implementations, 185// but classes optimized for code size may be happy with keeping them. See 186// the optimize_for option in descriptor.proto. 187class LIBPROTOBUF_EXPORT Message : public MessageLite { 188 public: 189 inline Message() {} 190 virtual ~Message(); 191 192 // Basic Operations ------------------------------------------------ 193 194 // Construct a new instance of the same type. Ownership is passed to the 195 // caller. (This is also defined in MessageLite, but is defined again here 196 // for return-type covariance.) 197 virtual Message* New() const = 0; 198 199 // Make this message into a copy of the given message. The given message 200 // must have the same descriptor, but need not necessarily be the same class. 201 // By default this is just implemented as "Clear(); MergeFrom(from);". 202 virtual void CopyFrom(const Message& from); 203 204 // Merge the fields from the given message into this message. Singular 205 // fields will be overwritten, except for embedded messages which will 206 // be merged. Repeated fields will be concatenated. The given message 207 // must be of the same type as this message (i.e. the exact same class). 208 virtual void MergeFrom(const Message& from); 209 210 // Verifies that IsInitialized() returns true. GOOGLE_CHECK-fails otherwise, with 211 // a nice error message. 212 void CheckInitialized() const; 213 214 // Slowly build a list of all required fields that are not set. 215 // This is much, much slower than IsInitialized() as it is implemented 216 // purely via reflection. Generally, you should not call this unless you 217 // have already determined that an error exists by calling IsInitialized(). 218 void FindInitializationErrors(vector<string>* errors) const; 219 220 // Like FindInitializationErrors, but joins all the strings, delimited by 221 // commas, and returns them. 222 string InitializationErrorString() const; 223 224 // Clears all unknown fields from this message and all embedded messages. 225 // Normally, if unknown tag numbers are encountered when parsing a message, 226 // the tag and value are stored in the message's UnknownFieldSet and 227 // then written back out when the message is serialized. This allows servers 228 // which simply route messages to other servers to pass through messages 229 // that have new field definitions which they don't yet know about. However, 230 // this behavior can have security implications. To avoid it, call this 231 // method after parsing. 232 // 233 // See Reflection::GetUnknownFields() for more on unknown fields. 234 virtual void DiscardUnknownFields(); 235 236 // Computes (an estimate of) the total number of bytes currently used for 237 // storing the message in memory. The default implementation calls the 238 // Reflection object's SpaceUsed() method. 239 virtual int SpaceUsed() const; 240 241 // Debugging ------------------------------------------------------- 242 243 // Generates a human readable form of this message, useful for debugging 244 // and other purposes. 245 string DebugString() const; 246 // Like DebugString(), but with less whitespace. 247 string ShortDebugString() const; 248 // Convenience function useful in GDB. Prints DebugString() to stdout. 249 void PrintDebugString() const; 250 251 // Heavy I/O ------------------------------------------------------- 252 // Additional parsing and serialization methods not implemented by 253 // MessageLite because they are not supported by the lite library. 254 255 // Parse a protocol buffer from a file descriptor. If successful, the entire 256 // input will be consumed. 257 bool ParseFromFileDescriptor(int file_descriptor); 258 // Like ParseFromFileDescriptor(), but accepts messages that are missing 259 // required fields. 260 bool ParsePartialFromFileDescriptor(int file_descriptor); 261 // Parse a protocol buffer from a C++ istream. If successful, the entire 262 // input will be consumed. 263 bool ParseFromIstream(istream* input); 264 // Like ParseFromIstream(), but accepts messages that are missing 265 // required fields. 266 bool ParsePartialFromIstream(istream* input); 267 268 // Serialize the message and write it to the given file descriptor. All 269 // required fields must be set. 270 bool SerializeToFileDescriptor(int file_descriptor) const; 271 // Like SerializeToFileDescriptor(), but allows missing required fields. 272 bool SerializePartialToFileDescriptor(int file_descriptor) const; 273 // Serialize the message and write it to the given C++ ostream. All 274 // required fields must be set. 275 bool SerializeToOstream(ostream* output) const; 276 // Like SerializeToOstream(), but allows missing required fields. 277 bool SerializePartialToOstream(ostream* output) const; 278 279 280 // Reflection-based methods ---------------------------------------- 281 // These methods are pure-virtual in MessageLite, but Message provides 282 // reflection-based default implementations. 283 284 virtual string GetTypeName() const; 285 virtual void Clear(); 286 virtual bool IsInitialized() const; 287 virtual void CheckTypeAndMergeFrom(const MessageLite& other); 288 virtual bool MergePartialFromCodedStream(io::CodedInputStream* input); 289 virtual int ByteSize() const; 290 virtual void SerializeWithCachedSizes(io::CodedOutputStream* output) const; 291 292 private: 293 // This is called only by the default implementation of ByteSize(), to 294 // update the cached size. If you override ByteSize(), you do not need 295 // to override this. If you do not override ByteSize(), you MUST override 296 // this; the default implementation will crash. 297 // 298 // The method is private because subclasses should never call it; only 299 // override it. Yes, C++ lets you do that. Crazy, huh? 300 virtual void SetCachedSize(int size) const; 301 302 public: 303 304 // Introspection --------------------------------------------------- 305 306 // Typedef for backwards-compatibility. 307 typedef google::protobuf::Reflection Reflection; 308 309 // Get a Descriptor for this message's type. This describes what 310 // fields the message contains, the types of those fields, etc. 311 const Descriptor* GetDescriptor() const { return GetMetadata().descriptor; } 312 313 // Get the Reflection interface for this Message, which can be used to 314 // read and modify the fields of the Message dynamically (in other words, 315 // without knowing the message type at compile time). This object remains 316 // property of the Message. 317 // 318 // This method remains virtual in case a subclass does not implement 319 // reflection and wants to override the default behavior. 320 virtual const Reflection* GetReflection() const { 321 return GetMetadata().reflection; 322 } 323 324 protected: 325 // Get a struct containing the metadata for the Message. Most subclasses only 326 // need to implement this method, rather than the GetDescriptor() and 327 // GetReflection() wrappers. 328 virtual Metadata GetMetadata() const = 0; 329 330 private: 331 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(Message); 332}; 333 334// This interface contains methods that can be used to dynamically access 335// and modify the fields of a protocol message. Their semantics are 336// similar to the accessors the protocol compiler generates. 337// 338// To get the Reflection for a given Message, call Message::GetReflection(). 339// 340// This interface is separate from Message only for efficiency reasons; 341// the vast majority of implementations of Message will share the same 342// implementation of Reflection (GeneratedMessageReflection, 343// defined in generated_message.h), and all Messages of a particular class 344// should share the same Reflection object (though you should not rely on 345// the latter fact). 346// 347// There are several ways that these methods can be used incorrectly. For 348// example, any of the following conditions will lead to undefined 349// results (probably assertion failures): 350// - The FieldDescriptor is not a field of this message type. 351// - The method called is not appropriate for the field's type. For 352// each field type in FieldDescriptor::TYPE_*, there is only one 353// Get*() method, one Set*() method, and one Add*() method that is 354// valid for that type. It should be obvious which (except maybe 355// for TYPE_BYTES, which are represented using strings in C++). 356// - A Get*() or Set*() method for singular fields is called on a repeated 357// field. 358// - GetRepeated*(), SetRepeated*(), or Add*() is called on a non-repeated 359// field. 360// - The Message object passed to any method is not of the right type for 361// this Reflection object (i.e. message.GetReflection() != reflection). 362// 363// You might wonder why there is not any abstract representation for a field 364// of arbitrary type. E.g., why isn't there just a "GetField()" method that 365// returns "const Field&", where "Field" is some class with accessors like 366// "GetInt32Value()". The problem is that someone would have to deal with 367// allocating these Field objects. For generated message classes, having to 368// allocate space for an additional object to wrap every field would at least 369// double the message's memory footprint, probably worse. Allocating the 370// objects on-demand, on the other hand, would be expensive and prone to 371// memory leaks. So, instead we ended up with this flat interface. 372// 373// TODO(kenton): Create a utility class which callers can use to read and 374// write fields from a Reflection without paying attention to the type. 375class LIBPROTOBUF_EXPORT Reflection { 376 public: 377 // TODO(kenton): Remove parameter. 378 inline Reflection() {} 379 virtual ~Reflection(); 380 381 // Get the UnknownFieldSet for the message. This contains fields which 382 // were seen when the Message was parsed but were not recognized according 383 // to the Message's definition. 384 virtual const UnknownFieldSet& GetUnknownFields( 385 const Message& message) const = 0; 386 // Get a mutable pointer to the UnknownFieldSet for the message. This 387 // contains fields which were seen when the Message was parsed but were not 388 // recognized according to the Message's definition. 389 virtual UnknownFieldSet* MutableUnknownFields(Message* message) const = 0; 390 391 // Estimate the amount of memory used by the message object. 392 virtual int SpaceUsed(const Message& message) const = 0; 393 394 // Check if the given non-repeated field is set. 395 virtual bool HasField(const Message& message, 396 const FieldDescriptor* field) const = 0; 397 398 // Get the number of elements of a repeated field. 399 virtual int FieldSize(const Message& message, 400 const FieldDescriptor* field) const = 0; 401 402 // Clear the value of a field, so that HasField() returns false or 403 // FieldSize() returns zero. 404 virtual void ClearField(Message* message, 405 const FieldDescriptor* field) const = 0; 406 407 // Remove the last element of a repeated field. 408 // We don't provide a way to remove any element other than the last 409 // because it invites inefficient use, such as O(n^2) filtering loops 410 // that should have been O(n). If you want to remove an element other 411 // than the last, the best way to do it is to re-arrange the elements 412 // (using Swap()) so that the one you want removed is at the end, then 413 // call RemoveLast(). 414 virtual void RemoveLast(Message* message, 415 const FieldDescriptor* field) const = 0; 416 417 // Swap the complete contents of two messages. 418 virtual void Swap(Message* message1, Message* message2) const = 0; 419 420 // Swap two elements of a repeated field. 421 virtual void SwapElements(Message* message, 422 const FieldDescriptor* field, 423 int index1, 424 int index2) const = 0; 425 426 // List all fields of the message which are currently set. This includes 427 // extensions. Singular fields will only be listed if HasField(field) would 428 // return true and repeated fields will only be listed if FieldSize(field) 429 // would return non-zero. Fields (both normal fields and extension fields) 430 // will be listed ordered by field number. 431 virtual void ListFields(const Message& message, 432 vector<const FieldDescriptor*>* output) const = 0; 433 434 // Singular field getters ------------------------------------------ 435 // These get the value of a non-repeated field. They return the default 436 // value for fields that aren't set. 437 438 virtual int32 GetInt32 (const Message& message, 439 const FieldDescriptor* field) const = 0; 440 virtual int64 GetInt64 (const Message& message, 441 const FieldDescriptor* field) const = 0; 442 virtual uint32 GetUInt32(const Message& message, 443 const FieldDescriptor* field) const = 0; 444 virtual uint64 GetUInt64(const Message& message, 445 const FieldDescriptor* field) const = 0; 446 virtual float GetFloat (const Message& message, 447 const FieldDescriptor* field) const = 0; 448 virtual double GetDouble(const Message& message, 449 const FieldDescriptor* field) const = 0; 450 virtual bool GetBool (const Message& message, 451 const FieldDescriptor* field) const = 0; 452 virtual string GetString(const Message& message, 453 const FieldDescriptor* field) const = 0; 454 virtual const EnumValueDescriptor* GetEnum( 455 const Message& message, const FieldDescriptor* field) const = 0; 456 virtual const Message& GetMessage(const Message& message, 457 const FieldDescriptor* field) const = 0; 458 459 // Get a string value without copying, if possible. 460 // 461 // GetString() necessarily returns a copy of the string. This can be 462 // inefficient when the string is already stored in a string object in the 463 // underlying message. GetStringReference() will return a reference to the 464 // underlying string in this case. Otherwise, it will copy the string into 465 // *scratch and return that. 466 // 467 // Note: It is perfectly reasonable and useful to write code like: 468 // str = reflection->GetStringReference(field, &str); 469 // This line would ensure that only one copy of the string is made 470 // regardless of the field's underlying representation. When initializing 471 // a newly-constructed string, though, it's just as fast and more readable 472 // to use code like: 473 // string str = reflection->GetString(field); 474 virtual const string& GetStringReference(const Message& message, 475 const FieldDescriptor* field, 476 string* scratch) const = 0; 477 478 479 // Singular field mutators ----------------------------------------- 480 // These mutate the value of a non-repeated field. 481 482 virtual void SetInt32 (Message* message, 483 const FieldDescriptor* field, int32 value) const = 0; 484 virtual void SetInt64 (Message* message, 485 const FieldDescriptor* field, int64 value) const = 0; 486 virtual void SetUInt32(Message* message, 487 const FieldDescriptor* field, uint32 value) const = 0; 488 virtual void SetUInt64(Message* message, 489 const FieldDescriptor* field, uint64 value) const = 0; 490 virtual void SetFloat (Message* message, 491 const FieldDescriptor* field, float value) const = 0; 492 virtual void SetDouble(Message* message, 493 const FieldDescriptor* field, double value) const = 0; 494 virtual void SetBool (Message* message, 495 const FieldDescriptor* field, bool value) const = 0; 496 virtual void SetString(Message* message, 497 const FieldDescriptor* field, 498 const string& value) const = 0; 499 virtual void SetEnum (Message* message, 500 const FieldDescriptor* field, 501 const EnumValueDescriptor* value) const = 0; 502 // Get a mutable pointer to a field with a message type. 503 virtual Message* MutableMessage(Message* message, 504 const FieldDescriptor* field) const = 0; 505 506 507 // Repeated field getters ------------------------------------------ 508 // These get the value of one element of a repeated field. 509 510 virtual int32 GetRepeatedInt32 (const Message& message, 511 const FieldDescriptor* field, 512 int index) const = 0; 513 virtual int64 GetRepeatedInt64 (const Message& message, 514 const FieldDescriptor* field, 515 int index) const = 0; 516 virtual uint32 GetRepeatedUInt32(const Message& message, 517 const FieldDescriptor* field, 518 int index) const = 0; 519 virtual uint64 GetRepeatedUInt64(const Message& message, 520 const FieldDescriptor* field, 521 int index) const = 0; 522 virtual float GetRepeatedFloat (const Message& message, 523 const FieldDescriptor* field, 524 int index) const = 0; 525 virtual double GetRepeatedDouble(const Message& message, 526 const FieldDescriptor* field, 527 int index) const = 0; 528 virtual bool GetRepeatedBool (const Message& message, 529 const FieldDescriptor* field, 530 int index) const = 0; 531 virtual string GetRepeatedString(const Message& message, 532 const FieldDescriptor* field, 533 int index) const = 0; 534 virtual const EnumValueDescriptor* GetRepeatedEnum( 535 const Message& message, 536 const FieldDescriptor* field, int index) const = 0; 537 virtual const Message& GetRepeatedMessage( 538 const Message& message, 539 const FieldDescriptor* field, int index) const = 0; 540 541 // See GetStringReference(), above. 542 virtual const string& GetRepeatedStringReference( 543 const Message& message, const FieldDescriptor* field, 544 int index, string* scratch) const = 0; 545 546 547 // Repeated field mutators ----------------------------------------- 548 // These mutate the value of one element of a repeated field. 549 550 virtual void SetRepeatedInt32 (Message* message, 551 const FieldDescriptor* field, 552 int index, int32 value) const = 0; 553 virtual void SetRepeatedInt64 (Message* message, 554 const FieldDescriptor* field, 555 int index, int64 value) const = 0; 556 virtual void SetRepeatedUInt32(Message* message, 557 const FieldDescriptor* field, 558 int index, uint32 value) const = 0; 559 virtual void SetRepeatedUInt64(Message* message, 560 const FieldDescriptor* field, 561 int index, uint64 value) const = 0; 562 virtual void SetRepeatedFloat (Message* message, 563 const FieldDescriptor* field, 564 int index, float value) const = 0; 565 virtual void SetRepeatedDouble(Message* message, 566 const FieldDescriptor* field, 567 int index, double value) const = 0; 568 virtual void SetRepeatedBool (Message* message, 569 const FieldDescriptor* field, 570 int index, bool value) const = 0; 571 virtual void SetRepeatedString(Message* message, 572 const FieldDescriptor* field, 573 int index, const string& value) const = 0; 574 virtual void SetRepeatedEnum(Message* message, 575 const FieldDescriptor* field, int index, 576 const EnumValueDescriptor* value) const = 0; 577 // Get a mutable pointer to an element of a repeated field with a message 578 // type. 579 virtual Message* MutableRepeatedMessage( 580 Message* message, const FieldDescriptor* field, int index) const = 0; 581 582 583 // Repeated field adders ------------------------------------------- 584 // These add an element to a repeated field. 585 586 virtual void AddInt32 (Message* message, 587 const FieldDescriptor* field, int32 value) const = 0; 588 virtual void AddInt64 (Message* message, 589 const FieldDescriptor* field, int64 value) const = 0; 590 virtual void AddUInt32(Message* message, 591 const FieldDescriptor* field, uint32 value) const = 0; 592 virtual void AddUInt64(Message* message, 593 const FieldDescriptor* field, uint64 value) const = 0; 594 virtual void AddFloat (Message* message, 595 const FieldDescriptor* field, float value) const = 0; 596 virtual void AddDouble(Message* message, 597 const FieldDescriptor* field, double value) const = 0; 598 virtual void AddBool (Message* message, 599 const FieldDescriptor* field, bool value) const = 0; 600 virtual void AddString(Message* message, 601 const FieldDescriptor* field, 602 const string& value) const = 0; 603 virtual void AddEnum (Message* message, 604 const FieldDescriptor* field, 605 const EnumValueDescriptor* value) const = 0; 606 virtual Message* AddMessage(Message* message, 607 const FieldDescriptor* field) 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__ 693