message.h revision 5821806d5e7f356e8fa4b058a389a808ea183019
15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Protocol Buffers - Google's data interchange format 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright 2008 Google Inc. All rights reserved. 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// http://code.google.com/p/protobuf/ 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Redistribution and use in source and binary forms, with or without 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// modification, are permitted provided that the following conditions are 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// met: 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// * Redistributions of source code must retain the above copyright 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// notice, this list of conditions and the following disclaimer. 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// * Redistributions in binary form must reproduce the above 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// copyright notice, this list of conditions and the following disclaimer 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// in the documentation and/or other materials provided with the 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// distribution. 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// * Neither the name of Google Inc. nor the names of its 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// contributors may be used to endorse or promote products derived from 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// this software without specific prior written permission. 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Author: kenton@google.com (Kenton Varda) 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Based on original Protocol Buffers design by 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Sanjay Ghemawat, Jeff Dean, and others. 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Defines Message, the abstract interface implemented by non-lite 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// protocol message objects. Although it's possible to implement this 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// interface manually, most users will use the protocol compiler to 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// generate implementations. 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Example usage: 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Say you have a message defined as: 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// message Foo { 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// optional string text = 1; 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// repeated int32 numbers = 2; 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// } 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Then, if you used the protocol compiler to generate a class from the above 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// definition, you could use it like so: 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// string data; // Will store a serialized version of the message. 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// { 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// // Create a message and serialize it. 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Foo foo; 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// foo.set_text("Hello World!"); 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// foo.add_numbers(1); 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// foo.add_numbers(5); 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// foo.add_numbers(42); 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// foo.SerializeToString(&data); 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// } 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// { 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// // Parse the serialized message and check that it contains the 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// // correct data. 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Foo foo; 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// foo.ParseFromString(data); 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// assert(foo.text() == "Hello World!"); 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// assert(foo.numbers_size() == 3); 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// assert(foo.numbers(0) == 1); 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// assert(foo.numbers(1) == 5); 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// assert(foo.numbers(2) == 42); 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// } 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// { 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// // Same as the last block, but do it dynamically via the Message 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// // reflection interface. 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Message* foo = new Foo; 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Descriptor* descriptor = foo->GetDescriptor(); 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// // Get the descriptors for the fields we're interested in and verify 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// // their types. 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// FieldDescriptor* text_field = descriptor->FindFieldByName("text"); 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// assert(text_field != NULL); 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// assert(text_field->type() == FieldDescriptor::TYPE_STRING); 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// assert(text_field->label() == FieldDescriptor::TYPE_OPTIONAL); 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// FieldDescriptor* numbers_field = descriptor->FindFieldByName("numbers"); 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// assert(numbers_field != NULL); 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// assert(numbers_field->type() == FieldDescriptor::TYPE_INT32); 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// assert(numbers_field->label() == FieldDescriptor::TYPE_REPEATED); 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// // Parse the message. 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// foo->ParseFromString(data); 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// // Use the reflection interface to examine the contents. 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// const Reflection* reflection = foo->GetReflection(); 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// assert(reflection->GetString(foo, text_field) == "Hello World!"); 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// assert(reflection->FieldSize(foo, numbers_field) == 3); 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// assert(reflection->GetRepeatedInt32(foo, numbers_field, 0) == 1); 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// assert(reflection->GetRepeatedInt32(foo, numbers_field, 1) == 5); 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// assert(reflection->GetRepeatedInt32(foo, numbers_field, 2) == 42); 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// delete foo; 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// } 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef GOOGLE_PROTOBUF_MESSAGE_H__ 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define GOOGLE_PROTOBUF_MESSAGE_H__ 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <vector> 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <string> 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifdef __DECCXX 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// HP C++'s iosfwd doesn't work. 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <iostream> 1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#else 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <iosfwd> 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <google/protobuf/message_lite.h> 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <google/protobuf/stubs/common.h> 1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace google { 1285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace protobuf { 1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Defined in this file. 1315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class Message; 1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class Reflection; 1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class MessageFactory; 1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Defined in other files. 1365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class Descriptor; // descriptor.h 1375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class FieldDescriptor; // descriptor.h 1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class EnumDescriptor; // descriptor.h 1395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class EnumValueDescriptor; // descriptor.h 1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace io { 1415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) class ZeroCopyInputStream; // zero_copy_stream.h 1425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) class ZeroCopyOutputStream; // zero_copy_stream.h 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) class CodedInputStream; // coded_stream.h 1445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) class CodedOutputStream; // coded_stream.h 1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} 1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class UnknownFieldSet; // unknown_field_set.h 1475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// A container to hold message metadata. 1495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)struct Metadata { 1505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const Descriptor* descriptor; 1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const Reflection* reflection; 1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 1535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Returns the EnumDescriptor for enum type E, which must be a 1555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// proto-declared enum type. Code generated by the protocol compiler 1565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// will include specializations of this template for each enum type declared. 1575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)template <typename E> 1585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)const EnumDescriptor* GetEnumDescriptor(); 1595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Abstract interface for protocol messages. 1615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 1625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// See also MessageLite, which contains most every-day operations. Message 1635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// adds descriptors and reflection on top of that. 1645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 1655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// The methods of this class that are virtual but not pure-virtual have 1665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// default implementations based on reflection. Message classes which are 1675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// optimized for speed will want to override these with faster implementations, 1685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// but classes optimized for code size may be happy with keeping them. See 1695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// the optimize_for option in descriptor.proto. 1705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class LIBPROTOBUF_EXPORT Message : public MessageLite { 1715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 1725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) inline Message() {} 1735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual ~Message(); 1745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Basic Operations ------------------------------------------------ 1765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Construct a new instance of the same type. Ownership is passed to the 1785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // caller. (This is also defined in MessageLite, but is defined again here 1795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // for return-type covariance.) 1805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual Message* New() const = 0; 1815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Make this message into a copy of the given message. The given message 1835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // must have the same descriptor, but need not necessarily be the same class. 1845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // By default this is just implemented as "Clear(); MergeFrom(from);". 1855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void CopyFrom(const Message& from); 1865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Merge the fields from the given message into this message. Singular 1885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // fields will be overwritten, except for embedded messages which will 1895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // be merged. Repeated fields will be concatenated. The given message 1905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // must be of the same type as this message (i.e. the exact same class). 1915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void MergeFrom(const Message& from); 1925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Verifies that IsInitialized() returns true. GOOGLE_CHECK-fails otherwise, with 1945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // a nice error message. 1955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void CheckInitialized() const; 1965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Slowly build a list of all required fields that are not set. 1985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This is much, much slower than IsInitialized() as it is implemented 1995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // purely via reflection. Generally, you should not call this unless you 2005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // have already determined that an error exists by calling IsInitialized(). 2015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void FindInitializationErrors(vector<string>* errors) const; 2025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Like FindInitializationErrors, but joins all the strings, delimited by 2045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // commas, and returns them. 2055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) string InitializationErrorString() const; 2065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Clears all unknown fields from this message and all embedded messages. 2085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Normally, if unknown tag numbers are encountered when parsing a message, 2095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the tag and value are stored in the message's UnknownFieldSet and 2105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // then written back out when the message is serialized. This allows servers 2115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // which simply route messages to other servers to pass through messages 2125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // that have new field definitions which they don't yet know about. However, 2135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // this behavior can have security implications. To avoid it, call this 2145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // method after parsing. 2155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 2165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // See Reflection::GetUnknownFields() for more on unknown fields. 2175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void DiscardUnknownFields(); 2185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Computes (an estimate of) the total number of bytes currently used for 2205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // storing the message in memory. The default implementation calls the 2215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Reflection object's SpaceUsed() method. 2225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int SpaceUsed() const; 2235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Debugging & Testing---------------------------------------------- 2255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Generates a human readable form of this message, useful for debugging 2275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // and other purposes. 2285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) string DebugString() const; 2295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Like DebugString(), but with less whitespace. 2305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) string ShortDebugString() const; 2315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Like DebugString(), but do not escape UTF-8 byte sequences. 2325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) string Utf8DebugString() const; 2335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Convenience function useful in GDB. Prints DebugString() to stdout. 2345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void PrintDebugString() const; 2355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Heavy I/O ------------------------------------------------------- 2375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Additional parsing and serialization methods not implemented by 2385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // MessageLite because they are not supported by the lite library. 2395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Parse a protocol buffer from a file descriptor. If successful, the entire 2415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // input will be consumed. 2425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool ParseFromFileDescriptor(int file_descriptor); 2435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Like ParseFromFileDescriptor(), but accepts messages that are missing 2445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // required fields. 2455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool ParsePartialFromFileDescriptor(int file_descriptor); 2465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Parse a protocol buffer from a C++ istream. If successful, the entire 2475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // input will be consumed. 2485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool ParseFromIstream(istream* input); 2495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Like ParseFromIstream(), but accepts messages that are missing 2505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // required fields. 2515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool ParsePartialFromIstream(istream* input); 2525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Serialize the message and write it to the given file descriptor. All 2545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // required fields must be set. 2555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool SerializeToFileDescriptor(int file_descriptor) const; 2565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Like SerializeToFileDescriptor(), but allows missing required fields. 2575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool SerializePartialToFileDescriptor(int file_descriptor) const; 2585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Serialize the message and write it to the given C++ ostream. All 2595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // required fields must be set. 2605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool SerializeToOstream(ostream* output) const; 2615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Like SerializeToOstream(), but allows missing required fields. 2625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool SerializePartialToOstream(ostream* output) const; 2635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Reflection-based methods ---------------------------------------- 2665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // These methods are pure-virtual in MessageLite, but Message provides 2675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // reflection-based default implementations. 2685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual string GetTypeName() const; 2705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void Clear(); 2715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual bool IsInitialized() const; 2725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void CheckTypeAndMergeFrom(const MessageLite& other); 2735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual bool MergePartialFromCodedStream(io::CodedInputStream* input); 2745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int ByteSize() const; 2755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SerializeWithCachedSizes(io::CodedOutputStream* output) const; 2765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) private: 2785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This is called only by the default implementation of ByteSize(), to 2795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // update the cached size. If you override ByteSize(), you do not need 2805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // to override this. If you do not override ByteSize(), you MUST override 2815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // this; the default implementation will crash. 2825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 2835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The method is private because subclasses should never call it; only 2845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // override it. Yes, C++ lets you do that. Crazy, huh? 2855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetCachedSize(int size) const; 2865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 2885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Introspection --------------------------------------------------- 2905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Typedef for backwards-compatibility. 2925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) typedef google::protobuf::Reflection Reflection; 2935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Get a Descriptor for this message's type. This describes what 2955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // fields the message contains, the types of those fields, etc. 2965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const Descriptor* GetDescriptor() const { return GetMetadata().descriptor; } 2975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Get the Reflection interface for this Message, which can be used to 2995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // read and modify the fields of the Message dynamically (in other words, 3005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // without knowing the message type at compile time). This object remains 3015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // property of the Message. 3025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 3035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This method remains virtual in case a subclass does not implement 3045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // reflection and wants to override the default behavior. 3055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual const Reflection* GetReflection() const { 3065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) return GetMetadata().reflection; 3075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) } 3085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) protected: 3105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Get a struct containing the metadata for the Message. Most subclasses only 3115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // need to implement this method, rather than the GetDescriptor() and 3125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // GetReflection() wrappers. 3135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual Metadata GetMetadata() const = 0; 3145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) private: 3175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(Message); 3185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 3195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// This interface contains methods that can be used to dynamically access 3215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// and modify the fields of a protocol message. Their semantics are 3225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// similar to the accessors the protocol compiler generates. 3235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 3245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// To get the Reflection for a given Message, call Message::GetReflection(). 3255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 3265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// This interface is separate from Message only for efficiency reasons; 3275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// the vast majority of implementations of Message will share the same 3285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// implementation of Reflection (GeneratedMessageReflection, 3295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// defined in generated_message.h), and all Messages of a particular class 3305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// should share the same Reflection object (though you should not rely on 3315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// the latter fact). 3325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 3335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// There are several ways that these methods can be used incorrectly. For 3345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// example, any of the following conditions will lead to undefined 3355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// results (probably assertion failures): 3365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// - The FieldDescriptor is not a field of this message type. 3375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// - The method called is not appropriate for the field's type. For 3385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// each field type in FieldDescriptor::TYPE_*, there is only one 3395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Get*() method, one Set*() method, and one Add*() method that is 3405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// valid for that type. It should be obvious which (except maybe 3415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// for TYPE_BYTES, which are represented using strings in C++). 3425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// - A Get*() or Set*() method for singular fields is called on a repeated 3435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// field. 3445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// - GetRepeated*(), SetRepeated*(), or Add*() is called on a non-repeated 3455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// field. 3465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// - The Message object passed to any method is not of the right type for 3475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// this Reflection object (i.e. message.GetReflection() != reflection). 3485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 3495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// You might wonder why there is not any abstract representation for a field 3505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// of arbitrary type. E.g., why isn't there just a "GetField()" method that 3515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// returns "const Field&", where "Field" is some class with accessors like 3525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// "GetInt32Value()". The problem is that someone would have to deal with 3535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// allocating these Field objects. For generated message classes, having to 3545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// allocate space for an additional object to wrap every field would at least 3555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// double the message's memory footprint, probably worse. Allocating the 3565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// objects on-demand, on the other hand, would be expensive and prone to 3575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// memory leaks. So, instead we ended up with this flat interface. 3585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 3595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// TODO(kenton): Create a utility class which callers can use to read and 3605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// write fields from a Reflection without paying attention to the type. 3615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class LIBPROTOBUF_EXPORT Reflection { 3625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 3635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // TODO(kenton): Remove parameter. 3645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) inline Reflection() {} 3655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual ~Reflection(); 3665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Get the UnknownFieldSet for the message. This contains fields which 3685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // were seen when the Message was parsed but were not recognized according 3695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // to the Message's definition. 3705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual const UnknownFieldSet& GetUnknownFields( 3715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const Message& message) const = 0; 3725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Get a mutable pointer to the UnknownFieldSet for the message. This 3735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // contains fields which were seen when the Message was parsed but were not 3745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // recognized according to the Message's definition. 3755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual UnknownFieldSet* MutableUnknownFields(Message* message) const = 0; 3765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Estimate the amount of memory used by the message object. 3785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int SpaceUsed(const Message& message) const = 0; 3795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Check if the given non-repeated field is set. 3815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual bool HasField(const Message& message, 3825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field) const = 0; 3835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Get the number of elements of a repeated field. 3855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int FieldSize(const Message& message, 3865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field) const = 0; 3875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Clear the value of a field, so that HasField() returns false or 3895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // FieldSize() returns zero. 3905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void ClearField(Message* message, 3915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field) const = 0; 3925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Remove the last element of a repeated field. 3945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // We don't provide a way to remove any element other than the last 3955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // because it invites inefficient use, such as O(n^2) filtering loops 3965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // that should have been O(n). If you want to remove an element other 3975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // than the last, the best way to do it is to re-arrange the elements 3985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // (using Swap()) so that the one you want removed is at the end, then 3995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // call RemoveLast(). 4005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void RemoveLast(Message* message, 4015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field) const = 0; 4025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Swap the complete contents of two messages. 4045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void Swap(Message* message1, Message* message2) const = 0; 4055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Swap two elements of a repeated field. 4075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SwapElements(Message* message, 4085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 4095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index1, 4105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index2) const = 0; 4115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // List all fields of the message which are currently set. This includes 4135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // extensions. Singular fields will only be listed if HasField(field) would 4145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // return true and repeated fields will only be listed if FieldSize(field) 4155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // would return non-zero. Fields (both normal fields and extension fields) 4165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // will be listed ordered by field number. 4175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void ListFields(const Message& message, 4185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) vector<const FieldDescriptor*>* output) const = 0; 4195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Singular field getters ------------------------------------------ 4215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // These get the value of a non-repeated field. They return the default 4225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // value for fields that aren't set. 4235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int32 GetInt32 (const Message& message, 4255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field) const = 0; 4265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int64 GetInt64 (const Message& message, 4275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field) const = 0; 4285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual uint32 GetUInt32(const Message& message, 4295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field) const = 0; 4305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual uint64 GetUInt64(const Message& message, 4315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field) const = 0; 4325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual float GetFloat (const Message& message, 4335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field) const = 0; 4345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual double GetDouble(const Message& message, 4355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field) const = 0; 4365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual bool GetBool (const Message& message, 4375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field) const = 0; 4385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual string GetString(const Message& message, 4395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field) const = 0; 4405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual const EnumValueDescriptor* GetEnum( 4415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const Message& message, const FieldDescriptor* field) const = 0; 4425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // See MutableMessage() for the meaning of the "factory" parameter. 4435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual const Message& GetMessage(const Message& message, 4445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 4455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) MessageFactory* factory = NULL) const = 0; 4465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Get a string value without copying, if possible. 4485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 4495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // GetString() necessarily returns a copy of the string. This can be 4505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // inefficient when the string is already stored in a string object in the 4515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // underlying message. GetStringReference() will return a reference to the 4525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // underlying string in this case. Otherwise, it will copy the string into 4535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // *scratch and return that. 4545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 4555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Note: It is perfectly reasonable and useful to write code like: 4565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // str = reflection->GetStringReference(field, &str); 4575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This line would ensure that only one copy of the string is made 4585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // regardless of the field's underlying representation. When initializing 4595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // a newly-constructed string, though, it's just as fast and more readable 4605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // to use code like: 4615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // string str = reflection->GetString(field); 4625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual const string& GetStringReference(const Message& message, 4635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 4645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) string* scratch) const = 0; 4655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Singular field mutators ----------------------------------------- 4685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // These mutate the value of a non-repeated field. 4695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetInt32 (Message* message, 4715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, int32 value) const = 0; 4725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetInt64 (Message* message, 4735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, int64 value) const = 0; 4745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetUInt32(Message* message, 4755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, uint32 value) const = 0; 4765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetUInt64(Message* message, 4775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, uint64 value) const = 0; 4785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetFloat (Message* message, 4795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, float value) const = 0; 4805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetDouble(Message* message, 4815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, double value) const = 0; 4825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetBool (Message* message, 4835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, bool value) const = 0; 4845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetString(Message* message, 4855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 4865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const string& value) const = 0; 4875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetEnum (Message* message, 4885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 4895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const EnumValueDescriptor* value) const = 0; 4905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Get a mutable pointer to a field with a message type. If a MessageFactory 4915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // is provided, it will be used to construct instances of the sub-message; 4925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // otherwise, the default factory is used. If the field is an extension that 4935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // does not live in the same pool as the containing message's descriptor (e.g. 4945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // it lives in an overlay pool), then a MessageFactory must be provided. 4955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // If you have no idea what that meant, then you probably don't need to worry 4965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // about it (don't provide a MessageFactory). WARNING: If the 4975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // FieldDescriptor is for a compiled-in extension, then 4985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // factory->GetPrototype(field->message_type() MUST return an instance of the 4995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // compiled-in class for this type, NOT DynamicMessage. 5005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual Message* MutableMessage(Message* message, 5015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) MessageFactory* factory = NULL) const = 0; 5035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Repeated field getters ------------------------------------------ 5065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // These get the value of one element of a repeated field. 5075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int32 GetRepeatedInt32 (const Message& message, 5095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index) const = 0; 5115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int64 GetRepeatedInt64 (const Message& message, 5125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index) const = 0; 5145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual uint32 GetRepeatedUInt32(const Message& message, 5155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index) const = 0; 5175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual uint64 GetRepeatedUInt64(const Message& message, 5185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index) const = 0; 5205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual float GetRepeatedFloat (const Message& message, 5215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index) const = 0; 5235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual double GetRepeatedDouble(const Message& message, 5245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index) const = 0; 5265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual bool GetRepeatedBool (const Message& message, 5275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index) const = 0; 5295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual string GetRepeatedString(const Message& message, 5305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index) const = 0; 5325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual const EnumValueDescriptor* GetRepeatedEnum( 5335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const Message& message, 5345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, int index) const = 0; 5355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual const Message& GetRepeatedMessage( 5365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const Message& message, 5375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, int index) const = 0; 5385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // See GetStringReference(), above. 5405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual const string& GetRepeatedStringReference( 5415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const Message& message, const FieldDescriptor* field, 5425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index, string* scratch) const = 0; 5435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Repeated field mutators ----------------------------------------- 5465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // These mutate the value of one element of a repeated field. 5475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetRepeatedInt32 (Message* message, 5495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index, int32 value) const = 0; 5515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetRepeatedInt64 (Message* message, 5525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index, int64 value) const = 0; 5545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetRepeatedUInt32(Message* message, 5555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index, uint32 value) const = 0; 5575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetRepeatedUInt64(Message* message, 5585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index, uint64 value) const = 0; 5605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetRepeatedFloat (Message* message, 5615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index, float value) const = 0; 5635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetRepeatedDouble(Message* message, 5645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index, double value) const = 0; 5665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetRepeatedBool (Message* message, 5675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index, bool value) const = 0; 5695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetRepeatedString(Message* message, 5705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 5715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int index, const string& value) const = 0; 5725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void SetRepeatedEnum(Message* message, 5735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, int index, 5745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const EnumValueDescriptor* value) const = 0; 5755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Get a mutable pointer to an element of a repeated field with a message 5765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // type. 5775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual Message* MutableRepeatedMessage( 5785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Message* message, const FieldDescriptor* field, int index) const = 0; 5795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Repeated field adders ------------------------------------------- 5825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // These add an element to a repeated field. 5835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void AddInt32 (Message* message, 5855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, int32 value) const = 0; 5865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void AddInt64 (Message* message, 5875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, int64 value) const = 0; 5885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void AddUInt32(Message* message, 5895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, uint32 value) const = 0; 5905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void AddUInt64(Message* message, 5915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, uint64 value) const = 0; 5925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void AddFloat (Message* message, 5935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, float value) const = 0; 5945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void AddDouble(Message* message, 5955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, double value) const = 0; 5965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void AddBool (Message* message, 5975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, bool value) const = 0; 5985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void AddString(Message* message, 5995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 6005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const string& value) const = 0; 6015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void AddEnum (Message* message, 6025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 6035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const EnumValueDescriptor* value) const = 0; 6045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // See MutableMessage() for comments on the "factory" parameter. 6055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual Message* AddMessage(Message* message, 6065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const FieldDescriptor* field, 6075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) MessageFactory* factory = NULL) const = 0; 6085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Extensions ------------------------------------------------------ 6115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Try to find an extension of this message type by fully-qualified field 6135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // name. Returns NULL if no extension is known for this name or number. 6145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual const FieldDescriptor* FindKnownExtensionByName( 6155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const string& name) const = 0; 6165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Try to find an extension of this message type by field number. 6185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns NULL if no extension is known for this name or number. 6195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual const FieldDescriptor* FindKnownExtensionByNumber( 6205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int number) const = 0; 6215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) private: 6235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(Reflection); 6245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 6255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Abstract interface for a factory for message objects. 6275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class LIBPROTOBUF_EXPORT MessageFactory { 6285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 6295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) inline MessageFactory() {} 6305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual ~MessageFactory(); 6315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Given a Descriptor, gets or constructs the default (prototype) Message 6335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // of that type. You can then call that message's New() method to construct 6345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // a mutable message of that type. 6355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 6365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Calling this method twice with the same Descriptor returns the same 6375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // object. The returned object remains property of the factory. Also, any 6385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // objects created by calling the prototype's New() method share some data 6395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // with the prototype, so these must be destoyed before the MessageFactory 6405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // is destroyed. 6415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 6425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The given descriptor must outlive the returned message, and hence must 6435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // outlive the MessageFactory. 6445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 6455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Some implementations do not support all types. GetPrototype() will 6465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // return NULL if the descriptor passed in is not supported. 6475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 6485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This method may or may not be thread-safe depending on the implementation. 6495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Each implementation should document its own degree thread-safety. 6505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual const Message* GetPrototype(const Descriptor* type) = 0; 6515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Gets a MessageFactory which supports all generated, compiled-in messages. 6535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // In other words, for any compiled-in type FooMessage, the following is true: 6545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // MessageFactory::generated_factory()->GetPrototype( 6555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // FooMessage::descriptor()) == FooMessage::default_instance() 6565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This factory supports all types which are found in 6575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // DescriptorPool::generated_pool(). If given a descriptor from any other 6585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // pool, GetPrototype() will return NULL. (You can also check if a 6595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // descriptor is for a generated message by checking if 6605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // descriptor->file()->pool() == DescriptorPool::generated_pool().) 6615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 6625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This factory is 100% thread-safe; calling GetPrototype() does not modify 6635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // any shared data. 6645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 6655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This factory is a singleton. The caller must not delete the object. 6665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static MessageFactory* generated_factory(); 6675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // For internal use only: Registers a .proto file at static initialization 6695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // time, to be placed in generated_factory. The first time GetPrototype() 6705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // is called with a descriptor from this file, |register_messages| will be 6715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // called, with the file name as the parameter. It must call 6725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // InternalRegisterGeneratedMessage() (below) to register each message type 6735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // in the file. This strange mechanism is necessary because descriptors are 6745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // built lazily, so we can't register types by their descriptor until we 6755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // know that the descriptor exists. |filename| must be a permanent string. 6765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static void InternalRegisterGeneratedFile( 6775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const char* filename, void (*register_messages)(const string&)); 6785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // For internal use only: Registers a message type. Called only by the 6805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // functions which are registered with InternalRegisterGeneratedFile(), 6815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // above. 6825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static void InternalRegisterGeneratedMessage(const Descriptor* descriptor, 6835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const Message* prototype); 6845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) private: 6865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(MessageFactory); 6875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 6885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace protobuf 6905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 6915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace google 6925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif // GOOGLE_PROTOBUF_MESSAGE_H__ 693