OLD | NEW |
1 // Protocol Buffers - Google's data interchange format | 1 // Protocol Buffers - Google's data interchange format |
2 // Copyright 2008 Google Inc. All rights reserved. | 2 // Copyright 2008 Google Inc. All rights reserved. |
3 // https://developers.google.com/protocol-buffers/ | 3 // https://developers.google.com/protocol-buffers/ |
4 // | 4 // |
5 // Redistribution and use in source and binary forms, with or without | 5 // Redistribution and use in source and binary forms, with or without |
6 // modification, are permitted provided that the following conditions are | 6 // modification, are permitted provided that the following conditions are |
7 // met: | 7 // met: |
8 // | 8 // |
9 // * Redistributions of source code must retain the above copyright | 9 // * Redistributions of source code must retain the above copyright |
10 // notice, this list of conditions and the following disclaimer. | 10 // notice, this list of conditions and the following disclaimer. |
(...skipping 161 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
172 // adds descriptors and reflection on top of that. | 172 // adds descriptors and reflection on top of that. |
173 // | 173 // |
174 // The methods of this class that are virtual but not pure-virtual have | 174 // The methods of this class that are virtual but not pure-virtual have |
175 // default implementations based on reflection. Message classes which are | 175 // default implementations based on reflection. Message classes which are |
176 // optimized for speed will want to override these with faster implementations, | 176 // optimized for speed will want to override these with faster implementations, |
177 // but classes optimized for code size may be happy with keeping them. See | 177 // but classes optimized for code size may be happy with keeping them. See |
178 // the optimize_for option in descriptor.proto. | 178 // the optimize_for option in descriptor.proto. |
179 class LIBPROTOBUF_EXPORT Message : public MessageLite { | 179 class LIBPROTOBUF_EXPORT Message : public MessageLite { |
180 public: | 180 public: |
181 inline Message() {} | 181 inline Message() {} |
182 virtual ~Message() {} | 182 virtual ~Message(); |
183 | 183 |
184 // Basic Operations ------------------------------------------------ | 184 // Basic Operations ------------------------------------------------ |
185 | 185 |
186 // Construct a new instance of the same type. Ownership is passed to the | 186 // Construct a new instance of the same type. Ownership is passed to the |
187 // caller. (This is also defined in MessageLite, but is defined again here | 187 // caller. (This is also defined in MessageLite, but is defined again here |
188 // for return-type covariance.) | 188 // for return-type covariance.) |
189 virtual Message* New() const = 0; | 189 virtual Message* New() const = 0; |
190 | 190 |
191 // Construct a new instance on the arena. Ownership is passed to the caller | 191 // Construct a new instance on the arena. Ownership is passed to the caller |
192 // if arena is a NULL. Default implementation allows for API compatibility | 192 // if arena is a NULL. Default implementation allows for API compatibility |
(...skipping 71 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
264 // MessageLite because they are not supported by the lite library. | 264 // MessageLite because they are not supported by the lite library. |
265 | 265 |
266 // Parse a protocol buffer from a file descriptor. If successful, the entire | 266 // Parse a protocol buffer from a file descriptor. If successful, the entire |
267 // input will be consumed. | 267 // input will be consumed. |
268 bool ParseFromFileDescriptor(int file_descriptor); | 268 bool ParseFromFileDescriptor(int file_descriptor); |
269 // Like ParseFromFileDescriptor(), but accepts messages that are missing | 269 // Like ParseFromFileDescriptor(), but accepts messages that are missing |
270 // required fields. | 270 // required fields. |
271 bool ParsePartialFromFileDescriptor(int file_descriptor); | 271 bool ParsePartialFromFileDescriptor(int file_descriptor); |
272 // Parse a protocol buffer from a C++ istream. If successful, the entire | 272 // Parse a protocol buffer from a C++ istream. If successful, the entire |
273 // input will be consumed. | 273 // input will be consumed. |
274 bool ParseFromIstream(std::istream* input); | 274 bool ParseFromIstream(istream* input); |
275 // Like ParseFromIstream(), but accepts messages that are missing | 275 // Like ParseFromIstream(), but accepts messages that are missing |
276 // required fields. | 276 // required fields. |
277 bool ParsePartialFromIstream(std::istream* input); | 277 bool ParsePartialFromIstream(istream* input); |
278 | 278 |
279 // Serialize the message and write it to the given file descriptor. All | 279 // Serialize the message and write it to the given file descriptor. All |
280 // required fields must be set. | 280 // required fields must be set. |
281 bool SerializeToFileDescriptor(int file_descriptor) const; | 281 bool SerializeToFileDescriptor(int file_descriptor) const; |
282 // Like SerializeToFileDescriptor(), but allows missing required fields. | 282 // Like SerializeToFileDescriptor(), but allows missing required fields. |
283 bool SerializePartialToFileDescriptor(int file_descriptor) const; | 283 bool SerializePartialToFileDescriptor(int file_descriptor) const; |
284 // Serialize the message and write it to the given C++ ostream. All | 284 // Serialize the message and write it to the given C++ ostream. All |
285 // required fields must be set. | 285 // required fields must be set. |
286 bool SerializeToOstream(std::ostream* output) const; | 286 bool SerializeToOstream(ostream* output) const; |
287 // Like SerializeToOstream(), but allows missing required fields. | 287 // Like SerializeToOstream(), but allows missing required fields. |
288 bool SerializePartialToOstream(std::ostream* output) const; | 288 bool SerializePartialToOstream(ostream* output) const; |
289 | 289 |
290 | 290 |
291 // Reflection-based methods ---------------------------------------- | 291 // Reflection-based methods ---------------------------------------- |
292 // These methods are pure-virtual in MessageLite, but Message provides | 292 // These methods are pure-virtual in MessageLite, but Message provides |
293 // reflection-based default implementations. | 293 // reflection-based default implementations. |
294 | 294 |
295 virtual string GetTypeName() const; | 295 virtual string GetTypeName() const; |
296 virtual void Clear(); | 296 virtual void Clear(); |
297 virtual bool IsInitialized() const; | 297 virtual bool IsInitialized() const; |
298 virtual void CheckTypeAndMergeFrom(const MessageLite& other); | 298 virtual void CheckTypeAndMergeFrom(const MessageLite& other); |
299 virtual bool MergePartialFromCodedStream(io::CodedInputStream* input); | 299 virtual bool MergePartialFromCodedStream(io::CodedInputStream* input); |
300 virtual size_t ByteSizeLong() const; | 300 virtual int ByteSize() const; |
301 virtual void SerializeWithCachedSizes(io::CodedOutputStream* output) const; | 301 virtual void SerializeWithCachedSizes(io::CodedOutputStream* output) const; |
302 | 302 |
303 private: | 303 private: |
304 // This is called only by the default implementation of ByteSize(), to | 304 // This is called only by the default implementation of ByteSize(), to |
305 // update the cached size. If you override ByteSize(), you do not need | 305 // update the cached size. If you override ByteSize(), you do not need |
306 // to override this. If you do not override ByteSize(), you MUST override | 306 // to override this. If you do not override ByteSize(), you MUST override |
307 // this; the default implementation will crash. | 307 // this; the default implementation will crash. |
308 // | 308 // |
309 // The method is private because subclasses should never call it; only | 309 // The method is private because subclasses should never call it; only |
310 // override it. Yes, C++ lets you do that. Crazy, huh? | 310 // override it. Yes, C++ lets you do that. Crazy, huh? |
(...skipping 201 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
512 const FieldDescriptor* field) const = 0; | 512 const FieldDescriptor* field) const = 0; |
513 virtual const EnumValueDescriptor* GetEnum( | 513 virtual const EnumValueDescriptor* GetEnum( |
514 const Message& message, const FieldDescriptor* field) const = 0; | 514 const Message& message, const FieldDescriptor* field) const = 0; |
515 | 515 |
516 // GetEnumValue() returns an enum field's value as an integer rather than | 516 // GetEnumValue() returns an enum field's value as an integer rather than |
517 // an EnumValueDescriptor*. If the integer value does not correspond to a | 517 // an EnumValueDescriptor*. If the integer value does not correspond to a |
518 // known value descriptor, a new value descriptor is created. (Such a value | 518 // known value descriptor, a new value descriptor is created. (Such a value |
519 // will only be present when the new unknown-enum-value semantics are enabled | 519 // will only be present when the new unknown-enum-value semantics are enabled |
520 // for a message.) | 520 // for a message.) |
521 virtual int GetEnumValue( | 521 virtual int GetEnumValue( |
522 const Message& message, const FieldDescriptor* field) const = 0; | 522 const Message& message, const FieldDescriptor* field) const; |
523 | 523 |
524 // See MutableMessage() for the meaning of the "factory" parameter. | 524 // See MutableMessage() for the meaning of the "factory" parameter. |
525 virtual const Message& GetMessage(const Message& message, | 525 virtual const Message& GetMessage(const Message& message, |
526 const FieldDescriptor* field, | 526 const FieldDescriptor* field, |
527 MessageFactory* factory = NULL) const = 0; | 527 MessageFactory* factory = NULL) const = 0; |
528 | 528 |
529 // Get a string value without copying, if possible. | 529 // Get a string value without copying, if possible. |
530 // | 530 // |
531 // GetString() necessarily returns a copy of the string. This can be | 531 // GetString() necessarily returns a copy of the string. This can be |
532 // inefficient when the string is already stored in a string object in the | 532 // inefficient when the string is already stored in a string object in the |
(...skipping 35 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
568 const string& value) const = 0; | 568 const string& value) const = 0; |
569 virtual void SetEnum (Message* message, | 569 virtual void SetEnum (Message* message, |
570 const FieldDescriptor* field, | 570 const FieldDescriptor* field, |
571 const EnumValueDescriptor* value) const = 0; | 571 const EnumValueDescriptor* value) const = 0; |
572 // Set an enum field's value with an integer rather than EnumValueDescriptor. | 572 // Set an enum field's value with an integer rather than EnumValueDescriptor. |
573 // If the value does not correspond to a known enum value, either behavior is | 573 // If the value does not correspond to a known enum value, either behavior is |
574 // undefined (for proto2 messages), or the value is accepted silently for | 574 // undefined (for proto2 messages), or the value is accepted silently for |
575 // messages with new unknown-enum-value semantics. | 575 // messages with new unknown-enum-value semantics. |
576 virtual void SetEnumValue(Message* message, | 576 virtual void SetEnumValue(Message* message, |
577 const FieldDescriptor* field, | 577 const FieldDescriptor* field, |
578 int value) const = 0; | 578 int value) const; |
579 | 579 |
580 // Get a mutable pointer to a field with a message type. If a MessageFactory | 580 // Get a mutable pointer to a field with a message type. If a MessageFactory |
581 // is provided, it will be used to construct instances of the sub-message; | 581 // is provided, it will be used to construct instances of the sub-message; |
582 // otherwise, the default factory is used. If the field is an extension that | 582 // otherwise, the default factory is used. If the field is an extension that |
583 // does not live in the same pool as the containing message's descriptor (e.g. | 583 // does not live in the same pool as the containing message's descriptor (e.g. |
584 // it lives in an overlay pool), then a MessageFactory must be provided. | 584 // it lives in an overlay pool), then a MessageFactory must be provided. |
585 // If you have no idea what that meant, then you probably don't need to worry | 585 // If you have no idea what that meant, then you probably don't need to worry |
586 // about it (don't provide a MessageFactory). WARNING: If the | 586 // about it (don't provide a MessageFactory). WARNING: If the |
587 // FieldDescriptor is for a compiled-in extension, then | 587 // FieldDescriptor is for a compiled-in extension, then |
588 // factory->GetPrototype(field->message_type()) MUST return an instance of | 588 // factory->GetPrototype(field->message_type() MUST return an instance of the |
589 // the compiled-in class for this type, NOT DynamicMessage. | 589 // compiled-in class for this type, NOT DynamicMessage. |
590 virtual Message* MutableMessage(Message* message, | 590 virtual Message* MutableMessage(Message* message, |
591 const FieldDescriptor* field, | 591 const FieldDescriptor* field, |
592 MessageFactory* factory = NULL) const = 0; | 592 MessageFactory* factory = NULL) const = 0; |
593 // Replaces the message specified by 'field' with the already-allocated object | 593 // Replaces the message specified by 'field' with the already-allocated object |
594 // sub_message, passing ownership to the message. If the field contained a | 594 // sub_message, passing ownership to the message. If the field contained a |
595 // message, that message is deleted. If sub_message is NULL, the field is | 595 // message, that message is deleted. If sub_message is NULL, the field is |
596 // cleared. | 596 // cleared. |
597 virtual void SetAllocatedMessage(Message* message, | 597 virtual void SetAllocatedMessage(Message* message, |
598 Message* sub_message, | 598 Message* sub_message, |
599 const FieldDescriptor* field) const = 0; | 599 const FieldDescriptor* field) const = 0; |
(...skipping 39 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
639 virtual const EnumValueDescriptor* GetRepeatedEnum( | 639 virtual const EnumValueDescriptor* GetRepeatedEnum( |
640 const Message& message, | 640 const Message& message, |
641 const FieldDescriptor* field, int index) const = 0; | 641 const FieldDescriptor* field, int index) const = 0; |
642 // GetRepeatedEnumValue() returns an enum field's value as an integer rather | 642 // GetRepeatedEnumValue() returns an enum field's value as an integer rather |
643 // than an EnumValueDescriptor*. If the integer value does not correspond to a | 643 // than an EnumValueDescriptor*. If the integer value does not correspond to a |
644 // known value descriptor, a new value descriptor is created. (Such a value | 644 // known value descriptor, a new value descriptor is created. (Such a value |
645 // will only be present when the new unknown-enum-value semantics are enabled | 645 // will only be present when the new unknown-enum-value semantics are enabled |
646 // for a message.) | 646 // for a message.) |
647 virtual int GetRepeatedEnumValue( | 647 virtual int GetRepeatedEnumValue( |
648 const Message& message, | 648 const Message& message, |
649 const FieldDescriptor* field, int index) const = 0; | 649 const FieldDescriptor* field, int index) const; |
650 virtual const Message& GetRepeatedMessage( | 650 virtual const Message& GetRepeatedMessage( |
651 const Message& message, | 651 const Message& message, |
652 const FieldDescriptor* field, int index) const = 0; | 652 const FieldDescriptor* field, int index) const = 0; |
653 | 653 |
654 // See GetStringReference(), above. | 654 // See GetStringReference(), above. |
655 virtual const string& GetRepeatedStringReference( | 655 virtual const string& GetRepeatedStringReference( |
656 const Message& message, const FieldDescriptor* field, | 656 const Message& message, const FieldDescriptor* field, |
657 int index, string* scratch) const = 0; | 657 int index, string* scratch) const = 0; |
658 | 658 |
659 | 659 |
(...skipping 26 matching lines...) Expand all Loading... |
686 int index, const string& value) const = 0; | 686 int index, const string& value) const = 0; |
687 virtual void SetRepeatedEnum(Message* message, | 687 virtual void SetRepeatedEnum(Message* message, |
688 const FieldDescriptor* field, int index, | 688 const FieldDescriptor* field, int index, |
689 const EnumValueDescriptor* value) const = 0; | 689 const EnumValueDescriptor* value) const = 0; |
690 // Set an enum field's value with an integer rather than EnumValueDescriptor. | 690 // Set an enum field's value with an integer rather than EnumValueDescriptor. |
691 // If the value does not correspond to a known enum value, either behavior is | 691 // If the value does not correspond to a known enum value, either behavior is |
692 // undefined (for proto2 messages), or the value is accepted silently for | 692 // undefined (for proto2 messages), or the value is accepted silently for |
693 // messages with new unknown-enum-value semantics. | 693 // messages with new unknown-enum-value semantics. |
694 virtual void SetRepeatedEnumValue(Message* message, | 694 virtual void SetRepeatedEnumValue(Message* message, |
695 const FieldDescriptor* field, int index, | 695 const FieldDescriptor* field, int index, |
696 int value) const = 0; | 696 int value) const; |
697 // Get a mutable pointer to an element of a repeated field with a message | 697 // Get a mutable pointer to an element of a repeated field with a message |
698 // type. | 698 // type. |
699 virtual Message* MutableRepeatedMessage( | 699 virtual Message* MutableRepeatedMessage( |
700 Message* message, const FieldDescriptor* field, int index) const = 0; | 700 Message* message, const FieldDescriptor* field, int index) const = 0; |
701 | 701 |
702 | 702 |
703 // Repeated field adders ------------------------------------------- | 703 // Repeated field adders ------------------------------------------- |
704 // These add an element to a repeated field. | 704 // These add an element to a repeated field. |
705 | 705 |
706 virtual void AddInt32 (Message* message, | 706 virtual void AddInt32 (Message* message, |
(...skipping 15 matching lines...) Expand all Loading... |
722 const string& value) const = 0; | 722 const string& value) const = 0; |
723 virtual void AddEnum (Message* message, | 723 virtual void AddEnum (Message* message, |
724 const FieldDescriptor* field, | 724 const FieldDescriptor* field, |
725 const EnumValueDescriptor* value) const = 0; | 725 const EnumValueDescriptor* value) const = 0; |
726 // Set an enum field's value with an integer rather than EnumValueDescriptor. | 726 // Set an enum field's value with an integer rather than EnumValueDescriptor. |
727 // If the value does not correspond to a known enum value, either behavior is | 727 // If the value does not correspond to a known enum value, either behavior is |
728 // undefined (for proto2 messages), or the value is accepted silently for | 728 // undefined (for proto2 messages), or the value is accepted silently for |
729 // messages with new unknown-enum-value semantics. | 729 // messages with new unknown-enum-value semantics. |
730 virtual void AddEnumValue(Message* message, | 730 virtual void AddEnumValue(Message* message, |
731 const FieldDescriptor* field, | 731 const FieldDescriptor* field, |
732 int value) const = 0; | 732 int value) const; |
733 // See MutableMessage() for comments on the "factory" parameter. | 733 // See MutableMessage() for comments on the "factory" parameter. |
734 virtual Message* AddMessage(Message* message, | 734 virtual Message* AddMessage(Message* message, |
735 const FieldDescriptor* field, | 735 const FieldDescriptor* field, |
736 MessageFactory* factory = NULL) const = 0; | 736 MessageFactory* factory = NULL) const = 0; |
737 | 737 |
738 // Appends an already-allocated object 'new_entry' to the repeated field | 738 // Appends an already-allocated object 'new_entry' to the repeated field |
739 // specifyed by 'field' passing ownership to the message. | 739 // specifyed by 'field' passing ownership to the message. |
740 // TODO(tmarek): Make virtual after all subclasses have been | 740 // TODO(tmarek): Make virtual after all subclasses have been |
741 // updated. | 741 // updated. |
742 virtual void AddAllocatedMessage(Message* /* message */, | 742 virtual void AddAllocatedMessage(Message* /* message */, |
(...skipping 98 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
841 // take arbitrary integer values, and the legacy GetEnum() getter will | 841 // take arbitrary integer values, and the legacy GetEnum() getter will |
842 // dynamically create an EnumValueDescriptor for any integer value without | 842 // dynamically create an EnumValueDescriptor for any integer value without |
843 // one. If |false|, setting an unknown enum value via the integer-based | 843 // one. If |false|, setting an unknown enum value via the integer-based |
844 // setters results in undefined behavior (in practice, GOOGLE_DCHECK-fails). | 844 // setters results in undefined behavior (in practice, GOOGLE_DCHECK-fails). |
845 // | 845 // |
846 // Generic code that uses reflection to handle messages with enum fields | 846 // Generic code that uses reflection to handle messages with enum fields |
847 // should check this flag before using the integer-based setter, and either | 847 // should check this flag before using the integer-based setter, and either |
848 // downgrade to a compatible value or use the UnknownFieldSet if not. For | 848 // downgrade to a compatible value or use the UnknownFieldSet if not. For |
849 // example: | 849 // example: |
850 // | 850 // |
851 // int new_value = GetValueFromApplicationLogic(); | 851 // int new_value = GetValueFromApplicationLogic(); |
852 // if (reflection->SupportsUnknownEnumValues()) { | 852 // if (reflection->SupportsUnknownEnumValues()) { |
853 // reflection->SetEnumValue(message, field, new_value); | 853 // reflection->SetEnumValue(message, field, new_value); |
854 // } else { | 854 // } else { |
855 // if (field_descriptor->enum_type()-> | 855 // if (field_descriptor->enum_type()-> |
856 // FindValueByNumver(new_value) != NULL) { | 856 // FindValueByNumver(new_value) != NULL) { |
857 // reflection->SetEnumValue(message, field, new_value); | 857 // reflection->SetEnumValue(message, field, new_value); |
858 // } else if (emit_unknown_enum_values) { | 858 // } else if (emit_unknown_enum_values) { |
859 // reflection->MutableUnknownFields(message)->AddVarint( | 859 // reflection->MutableUnknownFields(message)->AddVarint( |
860 // field->number(), new_value); | 860 // field->number(), |
| 861 // new_value); |
861 // } else { | 862 // } else { |
862 // // convert value to a compatible/default value. | 863 // // convert value to a compatible/default value. |
863 // new_value = CompatibleDowngrade(new_value); | 864 // new_value = CompatibleDowngrade(new_value); |
864 // reflection->SetEnumValue(message, field, new_value); | 865 // reflection->SetEnumValue(message, field, new_value); |
865 // } | 866 // } |
866 // } | 867 // } |
867 virtual bool SupportsUnknownEnumValues() const { return false; } | 868 virtual bool SupportsUnknownEnumValues() const { return false; } |
868 | 869 |
869 // Returns the MessageFactory associated with this message. This can be | 870 // Returns the MessageFactory associated with this message. This can be |
870 // useful for determining if a message is a generated message or not, for | 871 // useful for determining if a message is a generated message or not, for |
871 // example: | 872 // example: |
872 // if (message->GetReflection()->GetMessageFactory() == | 873 // |
873 // google::protobuf::MessageFactory::generated_factory()) { | 874 // if (message->GetReflection()->GetMessageFactory() == |
874 // // This is a generated message. | 875 // google::protobuf::MessageFactory::generated_factory()) { |
875 // } | 876 // // This is a generated message. |
| 877 // } |
| 878 // |
876 // It can also be used to create more messages of this type, though | 879 // It can also be used to create more messages of this type, though |
877 // Message::New() is an easier way to accomplish this. | 880 // Message::New() is an easier way to accomplish this. |
878 virtual MessageFactory* GetMessageFactory() const; | 881 virtual MessageFactory* GetMessageFactory() const; |
879 | 882 |
880 // --------------------------------------------------------------------------- | 883 // --------------------------------------------------------------------------- |
881 | 884 |
882 protected: | 885 protected: |
883 // Obtain a pointer to a Repeated Field Structure and do some type checking: | 886 // Obtain a pointer to a Repeated Field Structure and do some type checking: |
884 // on field->cpp_type(), | 887 // on field->cpp_type(), |
885 // on field->field_option().ctype() (if ctype >= 0) | 888 // on field->field_option().ctype() (if ctype >= 0) |
(...skipping 252 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1138 Message* message, const FieldDescriptor* field) const { | 1141 Message* message, const FieldDescriptor* field) const { |
1139 return static_cast<RepeatedPtrField<PB>* >( | 1142 return static_cast<RepeatedPtrField<PB>* >( |
1140 MutableRawRepeatedField(message, field, | 1143 MutableRawRepeatedField(message, field, |
1141 FieldDescriptor::CPPTYPE_MESSAGE, -1, | 1144 FieldDescriptor::CPPTYPE_MESSAGE, -1, |
1142 PB::default_instance().GetDescriptor())); | 1145 PB::default_instance().GetDescriptor())); |
1143 } | 1146 } |
1144 } // namespace protobuf | 1147 } // namespace protobuf |
1145 | 1148 |
1146 } // namespace google | 1149 } // namespace google |
1147 #endif // GOOGLE_PROTOBUF_MESSAGE_H__ | 1150 #endif // GOOGLE_PROTOBUF_MESSAGE_H__ |
OLD | NEW |