1 // Protocol Buffers - Google's data interchange format
2 // Copyright 2008 Google Inc. All rights reserved.
3 // http://code.google.com/p/protobuf/
5 // Redistribution and use in source and binary forms, with or without
6 // modification, are permitted provided that the following conditions are
9 // * Redistributions of source code must retain the above copyright
10 // notice, this list of conditions and the following disclaimer.
11 // * Redistributions in binary form must reproduce the above
12 // copyright notice, this list of conditions and the following disclaimer
13 // in the documentation and/or other materials provided with the
15 // * Neither the name of Google Inc. nor the names of its
16 // contributors may be used to endorse or promote products derived from
17 // this software without specific prior written permission.
19 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 // Author: kenton@google.com (Kenton Varda)
32 // Based on original Protocol Buffers design by
33 // Sanjay Ghemawat, Jeff Dean, and others.
35 // This file contains classes which describe a type of protocol message.
36 // You can use a message's descriptor to learn at runtime what fields
37 // it contains and what the types of those fields are. The Message
38 // interface also allows you to dynamically access and modify individual
39 // fields by passing the FieldDescriptor of the field you are interested
42 // Most users will not care about descriptors, because they will write
43 // code specific to certain protocol types and will simply use the classes
44 // generated by the protocol compiler directly. Advanced users who want
45 // to operate on arbitrary types (not known at compile time) may want to
46 // read descriptors in order to learn about the contents of a message.
47 // A very small number of users will want to construct their own
48 // Descriptors, either because they are implementing Message manually or
49 // because they are writing something like the protocol compiler.
51 // For an example of how you might use descriptors, see the code example
52 // at the top of message.h.
54 #ifndef GOOGLE_PROTOBUF_DESCRIPTOR_H__
55 #define GOOGLE_PROTOBUF_DESCRIPTOR_H__
59 #include <google/protobuf/stubs/common.h>
61 // TYPE_BOOL is defined in the MacOS's ConditionalMacros.h.
69 // Defined in this file.
71 class FieldDescriptor;
73 class EnumValueDescriptor;
74 class ServiceDescriptor;
75 class MethodDescriptor;
77 class DescriptorDatabase;
80 // Defined in descriptor.proto
81 class DescriptorProto;
82 class FieldDescriptorProto;
83 class EnumDescriptorProto;
84 class EnumValueDescriptorProto;
85 class ServiceDescriptorProto;
86 class MethodDescriptorProto;
87 class FileDescriptorProto;
91 class EnumValueOptions;
95 class UninterpretedOption;
98 // Defined in message.h
101 // Defined in descriptor.cc
102 class DescriptorBuilder;
103 class FileDescriptorTables;
105 // Defined in unknown_field_set.h.
108 // NB, all indices are zero-based.
109 struct SourceLocation {
115 // Doc comments found at the source location.
116 // TODO(kenton): Maybe this struct should have been named SourceInfo or
117 // something instead. Oh well.
118 string leading_comments;
119 string trailing_comments;
122 // Describes a type of protocol message, or a particular group within a
123 // message. To obtain the Descriptor for a given message object, call
124 // Message::GetDescriptor(). Generated message classes also have a
125 // static method called descriptor() which returns the type's descriptor.
126 // Use DescriptorPool to construct your own descriptors.
127 class LIBPROTOBUF_EXPORT Descriptor {
129 // The name of the message type, not including its scope.
130 const string& name() const;
132 // The fully-qualified name of the message type, scope delimited by
133 // periods. For example, message type "Foo" which is declared in package
134 // "bar" has full name "bar.Foo". If a type "Baz" is nested within
135 // Foo, Baz's full_name is "bar.Foo.Baz". To get only the part that
136 // comes after the last '.', use name().
137 const string& full_name() const;
139 // Index of this descriptor within the file or containing type's message
143 // The .proto file in which this message type was defined. Never NULL.
144 const FileDescriptor* file() const;
146 // If this Descriptor describes a nested type, this returns the type
147 // in which it is nested. Otherwise, returns NULL.
148 const Descriptor* containing_type() const;
150 // Get options for this message type. These are specified in the .proto file
151 // by placing lines like "option foo = 1234;" in the message definition.
152 // Allowed options are defined by MessageOptions in
153 // google/protobuf/descriptor.proto, and any available extensions of that
155 const MessageOptions& options() const;
157 // Write the contents of this Descriptor into the given DescriptorProto.
158 // The target DescriptorProto must be clear before calling this; if it
159 // isn't, the result may be garbage.
160 void CopyTo(DescriptorProto* proto) const;
162 // Write the contents of this decriptor in a human-readable form. Output
163 // will be suitable for re-parsing.
164 string DebugString() const;
166 // Field stuff -----------------------------------------------------
168 // The number of fields in this message type.
169 int field_count() const;
170 // Gets a field by index, where 0 <= index < field_count().
171 // These are returned in the order they were defined in the .proto file.
172 const FieldDescriptor* field(int index) const;
174 // Looks up a field by declared tag number. Returns NULL if no such field
176 const FieldDescriptor* FindFieldByNumber(int number) const;
177 // Looks up a field by name. Returns NULL if no such field exists.
178 const FieldDescriptor* FindFieldByName(const string& name) const;
180 // Looks up a field by lowercased name (as returned by lowercase_name()).
181 // This lookup may be ambiguous if multiple field names differ only by case,
182 // in which case the field returned is chosen arbitrarily from the matches.
183 const FieldDescriptor* FindFieldByLowercaseName(
184 const string& lowercase_name) const;
186 // Looks up a field by camel-case name (as returned by camelcase_name()).
187 // This lookup may be ambiguous if multiple field names differ in a way that
188 // leads them to have identical camel-case names, in which case the field
189 // returned is chosen arbitrarily from the matches.
190 const FieldDescriptor* FindFieldByCamelcaseName(
191 const string& camelcase_name) const;
193 // Nested type stuff -----------------------------------------------
195 // The number of nested types in this message type.
196 int nested_type_count() const;
197 // Gets a nested type by index, where 0 <= index < nested_type_count().
198 // These are returned in the order they were defined in the .proto file.
199 const Descriptor* nested_type(int index) const;
201 // Looks up a nested type by name. Returns NULL if no such nested type
203 const Descriptor* FindNestedTypeByName(const string& name) const;
205 // Enum stuff ------------------------------------------------------
207 // The number of enum types in this message type.
208 int enum_type_count() const;
209 // Gets an enum type by index, where 0 <= index < enum_type_count().
210 // These are returned in the order they were defined in the .proto file.
211 const EnumDescriptor* enum_type(int index) const;
213 // Looks up an enum type by name. Returns NULL if no such enum type exists.
214 const EnumDescriptor* FindEnumTypeByName(const string& name) const;
216 // Looks up an enum value by name, among all enum types in this message.
217 // Returns NULL if no such value exists.
218 const EnumValueDescriptor* FindEnumValueByName(const string& name) const;
220 // Extensions ------------------------------------------------------
222 // A range of field numbers which are designated for third-party
224 struct ExtensionRange {
225 int start; // inclusive
226 int end; // exclusive
229 // The number of extension ranges in this message type.
230 int extension_range_count() const;
231 // Gets an extension range by index, where 0 <= index <
232 // extension_range_count(). These are returned in the order they were defined
233 // in the .proto file.
234 const ExtensionRange* extension_range(int index) const;
236 // Returns true if the number is in one of the extension ranges.
237 bool IsExtensionNumber(int number) const;
239 // The number of extensions -- extending *other* messages -- that were
240 // defined nested within this message type's scope.
241 int extension_count() const;
242 // Get an extension by index, where 0 <= index < extension_count().
243 // These are returned in the order they were defined in the .proto file.
244 const FieldDescriptor* extension(int index) const;
246 // Looks up a named extension (which extends some *other* message type)
247 // defined within this message type's scope.
248 const FieldDescriptor* FindExtensionByName(const string& name) const;
250 // Similar to FindFieldByLowercaseName(), but finds extensions defined within
251 // this message type's scope.
252 const FieldDescriptor* FindExtensionByLowercaseName(const string& name) const;
254 // Similar to FindFieldByCamelcaseName(), but finds extensions defined within
255 // this message type's scope.
256 const FieldDescriptor* FindExtensionByCamelcaseName(const string& name) const;
258 // Source Location ---------------------------------------------------
260 // Updates |*out_location| to the source location of the complete
261 // extent of this message declaration. Returns false and leaves
262 // |*out_location| unchanged iff location information was not available.
263 bool GetSourceLocation(SourceLocation* out_location) const;
266 typedef MessageOptions OptionsType;
268 // Internal version of DebugString; controls the level of indenting for
270 void DebugString(int depth, string *contents) const;
272 // Walks up the descriptor tree to generate the source location path
273 // to this descriptor from the file root.
274 void GetLocationPath(vector<int>* output) const;
277 const string* full_name_;
278 const FileDescriptor* file_;
279 const Descriptor* containing_type_;
280 const MessageOptions* options_;
282 // True if this is a placeholder for an unknown type.
283 bool is_placeholder_;
284 // True if this is a placeholder and the type name wasn't fully-qualified.
285 bool is_unqualified_placeholder_;
288 FieldDescriptor* fields_;
289 int nested_type_count_;
290 Descriptor* nested_types_;
291 int enum_type_count_;
292 EnumDescriptor* enum_types_;
293 int extension_range_count_;
294 ExtensionRange* extension_ranges_;
295 int extension_count_;
296 FieldDescriptor* extensions_;
297 // IMPORTANT: If you add a new field, make sure to search for all instances
298 // of Allocate<Descriptor>() and AllocateArray<Descriptor>() in descriptor.cc
299 // and update them to initialize the field.
301 // Must be constructed using DescriptorPool.
303 friend class DescriptorBuilder;
304 friend class EnumDescriptor;
305 friend class FieldDescriptor;
306 friend class MethodDescriptor;
307 friend class FileDescriptor;
308 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(Descriptor);
311 // Describes a single field of a message. To get the descriptor for a given
312 // field, first get the Descriptor for the message in which it is defined,
313 // then call Descriptor::FindFieldByName(). To get a FieldDescriptor for
314 // an extension, do one of the following:
315 // - Get the Descriptor or FileDescriptor for its containing scope, then
316 // call Descriptor::FindExtensionByName() or
317 // FileDescriptor::FindExtensionByName().
318 // - Given a DescriptorPool, call DescriptorPool::FindExtensionByNumber().
319 // - Given a Reflection for a message object, call
320 // Reflection::FindKnownExtensionByName() or
321 // Reflection::FindKnownExtensionByNumber().
322 // Use DescriptorPool to construct your own descriptors.
323 class LIBPROTOBUF_EXPORT FieldDescriptor {
325 // Identifies a field type. 0 is reserved for errors. The order is weird
326 // for historical reasons. Types 12 and up are new in proto2.
328 TYPE_DOUBLE = 1, // double, exactly eight bytes on the wire.
329 TYPE_FLOAT = 2, // float, exactly four bytes on the wire.
330 TYPE_INT64 = 3, // int64, varint on the wire. Negative numbers
331 // take 10 bytes. Use TYPE_SINT64 if negative
332 // values are likely.
333 TYPE_UINT64 = 4, // uint64, varint on the wire.
334 TYPE_INT32 = 5, // int32, varint on the wire. Negative numbers
335 // take 10 bytes. Use TYPE_SINT32 if negative
336 // values are likely.
337 TYPE_FIXED64 = 6, // uint64, exactly eight bytes on the wire.
338 TYPE_FIXED32 = 7, // uint32, exactly four bytes on the wire.
339 TYPE_BOOL = 8, // bool, varint on the wire.
340 TYPE_STRING = 9, // UTF-8 text.
341 TYPE_GROUP = 10, // Tag-delimited message. Deprecated.
342 TYPE_MESSAGE = 11, // Length-delimited message.
344 TYPE_BYTES = 12, // Arbitrary byte array.
345 TYPE_UINT32 = 13, // uint32, varint on the wire
346 TYPE_ENUM = 14, // Enum, varint on the wire
347 TYPE_SFIXED32 = 15, // int32, exactly four bytes on the wire
348 TYPE_SFIXED64 = 16, // int64, exactly eight bytes on the wire
349 TYPE_SINT32 = 17, // int32, ZigZag-encoded varint on the wire
350 TYPE_SINT64 = 18, // int64, ZigZag-encoded varint on the wire
352 MAX_TYPE = 18, // Constant useful for defining lookup tables
356 // Specifies the C++ data type used to represent the field. There is a
357 // fixed mapping from Type to CppType where each Type maps to exactly one
358 // CppType. 0 is reserved for errors.
360 CPPTYPE_INT32 = 1, // TYPE_INT32, TYPE_SINT32, TYPE_SFIXED32
361 CPPTYPE_INT64 = 2, // TYPE_INT64, TYPE_SINT64, TYPE_SFIXED64
362 CPPTYPE_UINT32 = 3, // TYPE_UINT32, TYPE_FIXED32
363 CPPTYPE_UINT64 = 4, // TYPE_UINT64, TYPE_FIXED64
364 CPPTYPE_DOUBLE = 5, // TYPE_DOUBLE
365 CPPTYPE_FLOAT = 6, // TYPE_FLOAT
366 CPPTYPE_BOOL = 7, // TYPE_BOOL
367 CPPTYPE_ENUM = 8, // TYPE_ENUM
368 CPPTYPE_STRING = 9, // TYPE_STRING, TYPE_BYTES
369 CPPTYPE_MESSAGE = 10, // TYPE_MESSAGE, TYPE_GROUP
371 MAX_CPPTYPE = 10, // Constant useful for defining lookup tables
372 // indexed by CppType.
375 // Identifies whether the field is optional, required, or repeated. 0 is
376 // reserved for errors.
378 LABEL_OPTIONAL = 1, // optional
379 LABEL_REQUIRED = 2, // required
380 LABEL_REPEATED = 3, // repeated
382 MAX_LABEL = 3, // Constant useful for defining lookup tables
386 // Valid field numbers are positive integers up to kMaxNumber.
387 static const int kMaxNumber = (1 << 29) - 1;
389 // First field number reserved for the protocol buffer library implementation.
390 // Users may not declare fields that use reserved numbers.
391 static const int kFirstReservedNumber = 19000;
392 // Last field number reserved for the protocol buffer library implementation.
393 // Users may not declare fields that use reserved numbers.
394 static const int kLastReservedNumber = 19999;
396 const string& name() const; // Name of this field within the message.
397 const string& full_name() const; // Fully-qualified name of the field.
398 const FileDescriptor* file() const;// File in which this field was defined.
399 bool is_extension() const; // Is this an extension field?
400 int number() const; // Declared tag number.
402 // Same as name() except converted to lower-case. This (and especially the
403 // FindFieldByLowercaseName() method) can be useful when parsing formats
404 // which prefer to use lowercase naming style. (Although, technically
405 // field names should be lowercased anyway according to the protobuf style
406 // guide, so this only makes a difference when dealing with old .proto files
407 // which do not follow the guide.)
408 const string& lowercase_name() const;
410 // Same as name() except converted to camel-case. In this conversion, any
411 // time an underscore appears in the name, it is removed and the next
412 // letter is capitalized. Furthermore, the first letter of the name is
413 // lower-cased. Examples:
417 // This (and especially the FindFieldByCamelcaseName() method) can be useful
418 // when parsing formats which prefer to use camel-case naming style.
419 const string& camelcase_name() const;
421 Type type() const; // Declared type of this field.
422 const char* type_name() const; // Name of the declared type.
423 CppType cpp_type() const; // C++ type of this field.
424 const char* cpp_type_name() const; // Name of the C++ type.
425 Label label() const; // optional/required/repeated
427 bool is_required() const; // shorthand for label() == LABEL_REQUIRED
428 bool is_optional() const; // shorthand for label() == LABEL_OPTIONAL
429 bool is_repeated() const; // shorthand for label() == LABEL_REPEATED
430 bool is_packable() const; // shorthand for is_repeated() &&
431 // IsTypePackable(type())
432 bool is_packed() const; // shorthand for is_packable() &&
433 // options().packed()
435 // Index of this field within the message's field array, or the file or
436 // extension scope's extensions array.
439 // Does this field have an explicitly-declared default value?
440 bool has_default_value() const;
442 // Get the field default value if cpp_type() == CPPTYPE_INT32. If no
443 // explicit default was defined, the default is 0.
444 int32 default_value_int32() const;
445 // Get the field default value if cpp_type() == CPPTYPE_INT64. If no
446 // explicit default was defined, the default is 0.
447 int64 default_value_int64() const;
448 // Get the field default value if cpp_type() == CPPTYPE_UINT32. If no
449 // explicit default was defined, the default is 0.
450 uint32 default_value_uint32() const;
451 // Get the field default value if cpp_type() == CPPTYPE_UINT64. If no
452 // explicit default was defined, the default is 0.
453 uint64 default_value_uint64() const;
454 // Get the field default value if cpp_type() == CPPTYPE_FLOAT. If no
455 // explicit default was defined, the default is 0.0.
456 float default_value_float() const;
457 // Get the field default value if cpp_type() == CPPTYPE_DOUBLE. If no
458 // explicit default was defined, the default is 0.0.
459 double default_value_double() const;
460 // Get the field default value if cpp_type() == CPPTYPE_BOOL. If no
461 // explicit default was defined, the default is false.
462 bool default_value_bool() const;
463 // Get the field default value if cpp_type() == CPPTYPE_ENUM. If no
464 // explicit default was defined, the default is the first value defined
465 // in the enum type (all enum types are required to have at least one value).
466 // This never returns NULL.
467 const EnumValueDescriptor* default_value_enum() const;
468 // Get the field default value if cpp_type() == CPPTYPE_STRING. If no
469 // explicit default was defined, the default is the empty string.
470 const string& default_value_string() const;
472 // The Descriptor for the message of which this is a field. For extensions,
473 // this is the extended type. Never NULL.
474 const Descriptor* containing_type() const;
476 // An extension may be declared within the scope of another message. If this
477 // field is an extension (is_extension() is true), then extension_scope()
478 // returns that message, or NULL if the extension was declared at global
479 // scope. If this is not an extension, extension_scope() is undefined (may
481 const Descriptor* extension_scope() const;
483 // If type is TYPE_MESSAGE or TYPE_GROUP, returns a descriptor for the
484 // message or the group type. Otherwise, undefined.
485 const Descriptor* message_type() const;
486 // If type is TYPE_ENUM, returns a descriptor for the enum. Otherwise,
488 const EnumDescriptor* enum_type() const;
490 // EXPERIMENTAL; DO NOT USE.
491 // If this field is a map field, experimental_map_key() is the field
492 // that is the key for this map.
493 // experimental_map_key()->containing_type() is the same as message_type().
494 const FieldDescriptor* experimental_map_key() const;
496 // Get the FieldOptions for this field. This includes things listed in
497 // square brackets after the field definition. E.g., the field:
498 // optional string text = 1 [ctype=CORD];
499 // has the "ctype" option set. Allowed options are defined by FieldOptions
500 // in google/protobuf/descriptor.proto, and any available extensions of that
502 const FieldOptions& options() const;
504 // See Descriptor::CopyTo().
505 void CopyTo(FieldDescriptorProto* proto) const;
507 // See Descriptor::DebugString().
508 string DebugString() const;
510 // Helper method to get the CppType for a particular Type.
511 static CppType TypeToCppType(Type type);
513 // Return true iff [packed = true] is valid for fields of this type.
514 static inline bool IsTypePackable(Type field_type);
516 // Source Location ---------------------------------------------------
518 // Updates |*out_location| to the source location of the complete
519 // extent of this field declaration. Returns false and leaves
520 // |*out_location| unchanged iff location information was not available.
521 bool GetSourceLocation(SourceLocation* out_location) const;
524 typedef FieldOptions OptionsType;
526 // See Descriptor::DebugString().
527 void DebugString(int depth, string *contents) const;
529 // formats the default value appropriately and returns it as a string.
530 // Must have a default value to call this. If quote_string_type is true, then
531 // types of CPPTYPE_STRING whill be surrounded by quotes and CEscaped.
532 string DefaultValueAsString(bool quote_string_type) const;
534 // Walks up the descriptor tree to generate the source location path
535 // to this descriptor from the file root.
536 void GetLocationPath(vector<int>* output) const;
539 const string* full_name_;
540 const string* lowercase_name_;
541 const string* camelcase_name_;
542 const FileDescriptor* file_;
547 const Descriptor* containing_type_;
548 const Descriptor* extension_scope_;
549 const Descriptor* message_type_;
550 const EnumDescriptor* enum_type_;
551 const FieldDescriptor* experimental_map_key_;
552 const FieldOptions* options_;
553 // IMPORTANT: If you add a new field, make sure to search for all instances
554 // of Allocate<FieldDescriptor>() and AllocateArray<FieldDescriptor>() in
555 // descriptor.cc and update them to initialize the field.
557 bool has_default_value_;
559 int32 default_value_int32_;
560 int64 default_value_int64_;
561 uint32 default_value_uint32_;
562 uint64 default_value_uint64_;
563 float default_value_float_;
564 double default_value_double_;
565 bool default_value_bool_;
567 const EnumValueDescriptor* default_value_enum_;
568 const string* default_value_string_;
571 static const CppType kTypeToCppTypeMap[MAX_TYPE + 1];
573 static const char * const kTypeToName[MAX_TYPE + 1];
575 static const char * const kCppTypeToName[MAX_CPPTYPE + 1];
577 static const char * const kLabelToName[MAX_LABEL + 1];
579 // Must be constructed using DescriptorPool.
581 friend class DescriptorBuilder;
582 friend class FileDescriptor;
583 friend class Descriptor;
584 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(FieldDescriptor);
587 // Describes an enum type defined in a .proto file. To get the EnumDescriptor
588 // for a generated enum type, call TypeName_descriptor(). Use DescriptorPool
589 // to construct your own descriptors.
590 class LIBPROTOBUF_EXPORT EnumDescriptor {
592 // The name of this enum type in the containing scope.
593 const string& name() const;
595 // The fully-qualified name of the enum type, scope delimited by periods.
596 const string& full_name() const;
598 // Index of this enum within the file or containing message's enum array.
601 // The .proto file in which this enum type was defined. Never NULL.
602 const FileDescriptor* file() const;
604 // The number of values for this EnumDescriptor. Guaranteed to be greater
606 int value_count() const;
607 // Gets a value by index, where 0 <= index < value_count().
608 // These are returned in the order they were defined in the .proto file.
609 const EnumValueDescriptor* value(int index) const;
611 // Looks up a value by name. Returns NULL if no such value exists.
612 const EnumValueDescriptor* FindValueByName(const string& name) const;
613 // Looks up a value by number. Returns NULL if no such value exists. If
614 // multiple values have this number, the first one defined is returned.
615 const EnumValueDescriptor* FindValueByNumber(int number) const;
617 // If this enum type is nested in a message type, this is that message type.
619 const Descriptor* containing_type() const;
621 // Get options for this enum type. These are specified in the .proto file by
622 // placing lines like "option foo = 1234;" in the enum definition. Allowed
623 // options are defined by EnumOptions in google/protobuf/descriptor.proto,
624 // and any available extensions of that message.
625 const EnumOptions& options() const;
627 // See Descriptor::CopyTo().
628 void CopyTo(EnumDescriptorProto* proto) const;
630 // See Descriptor::DebugString().
631 string DebugString() const;
633 // Source Location ---------------------------------------------------
635 // Updates |*out_location| to the source location of the complete
636 // extent of this enum declaration. Returns false and leaves
637 // |*out_location| unchanged iff location information was not available.
638 bool GetSourceLocation(SourceLocation* out_location) const;
641 typedef EnumOptions OptionsType;
643 // See Descriptor::DebugString().
644 void DebugString(int depth, string *contents) const;
646 // Walks up the descriptor tree to generate the source location path
647 // to this descriptor from the file root.
648 void GetLocationPath(vector<int>* output) const;
651 const string* full_name_;
652 const FileDescriptor* file_;
653 const Descriptor* containing_type_;
654 const EnumOptions* options_;
656 // True if this is a placeholder for an unknown type.
657 bool is_placeholder_;
658 // True if this is a placeholder and the type name wasn't fully-qualified.
659 bool is_unqualified_placeholder_;
662 EnumValueDescriptor* values_;
663 // IMPORTANT: If you add a new field, make sure to search for all instances
664 // of Allocate<EnumDescriptor>() and AllocateArray<EnumDescriptor>() in
665 // descriptor.cc and update them to initialize the field.
667 // Must be constructed using DescriptorPool.
669 friend class DescriptorBuilder;
670 friend class Descriptor;
671 friend class FieldDescriptor;
672 friend class EnumValueDescriptor;
673 friend class FileDescriptor;
674 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(EnumDescriptor);
677 // Describes an individual enum constant of a particular type. To get the
678 // EnumValueDescriptor for a given enum value, first get the EnumDescriptor
679 // for its type, then use EnumDescriptor::FindValueByName() or
680 // EnumDescriptor::FindValueByNumber(). Use DescriptorPool to construct
681 // your own descriptors.
682 class LIBPROTOBUF_EXPORT EnumValueDescriptor {
684 const string& name() const; // Name of this enum constant.
685 int index() const; // Index within the enums's Descriptor.
686 int number() const; // Numeric value of this enum constant.
688 // The full_name of an enum value is a sibling symbol of the enum type.
689 // e.g. the full name of FieldDescriptorProto::TYPE_INT32 is actually
690 // "google.protobuf.FieldDescriptorProto.TYPE_INT32", NOT
691 // "google.protobuf.FieldDescriptorProto.Type.TYPE_INT32". This is to conform
692 // with C++ scoping rules for enums.
693 const string& full_name() const;
695 // The type of this value. Never NULL.
696 const EnumDescriptor* type() const;
698 // Get options for this enum value. These are specified in the .proto file
699 // by adding text like "[foo = 1234]" after an enum value definition.
700 // Allowed options are defined by EnumValueOptions in
701 // google/protobuf/descriptor.proto, and any available extensions of that
703 const EnumValueOptions& options() const;
705 // See Descriptor::CopyTo().
706 void CopyTo(EnumValueDescriptorProto* proto) const;
708 // See Descriptor::DebugString().
709 string DebugString() const;
711 // Source Location ---------------------------------------------------
713 // Updates |*out_location| to the source location of the complete
714 // extent of this enum value declaration. Returns false and leaves
715 // |*out_location| unchanged iff location information was not available.
716 bool GetSourceLocation(SourceLocation* out_location) const;
719 typedef EnumValueOptions OptionsType;
721 // See Descriptor::DebugString().
722 void DebugString(int depth, string *contents) const;
724 // Walks up the descriptor tree to generate the source location path
725 // to this descriptor from the file root.
726 void GetLocationPath(vector<int>* output) const;
729 const string* full_name_;
731 const EnumDescriptor* type_;
732 const EnumValueOptions* options_;
733 // IMPORTANT: If you add a new field, make sure to search for all instances
734 // of Allocate<EnumValueDescriptor>() and AllocateArray<EnumValueDescriptor>()
735 // in descriptor.cc and update them to initialize the field.
737 // Must be constructed using DescriptorPool.
738 EnumValueDescriptor() {}
739 friend class DescriptorBuilder;
740 friend class EnumDescriptor;
741 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(EnumValueDescriptor);
744 // Describes an RPC service. To get the ServiceDescriptor for a service,
745 // call Service::GetDescriptor(). Generated service classes also have a
746 // static method called descriptor() which returns the type's
747 // ServiceDescriptor. Use DescriptorPool to construct your own descriptors.
748 class LIBPROTOBUF_EXPORT ServiceDescriptor {
750 // The name of the service, not including its containing scope.
751 const string& name() const;
752 // The fully-qualified name of the service, scope delimited by periods.
753 const string& full_name() const;
754 // Index of this service within the file's services array.
757 // The .proto file in which this service was defined. Never NULL.
758 const FileDescriptor* file() const;
760 // Get options for this service type. These are specified in the .proto file
761 // by placing lines like "option foo = 1234;" in the service definition.
762 // Allowed options are defined by ServiceOptions in
763 // google/protobuf/descriptor.proto, and any available extensions of that
765 const ServiceOptions& options() const;
767 // The number of methods this service defines.
768 int method_count() const;
769 // Gets a MethodDescriptor by index, where 0 <= index < method_count().
770 // These are returned in the order they were defined in the .proto file.
771 const MethodDescriptor* method(int index) const;
773 // Look up a MethodDescriptor by name.
774 const MethodDescriptor* FindMethodByName(const string& name) const;
775 // See Descriptor::CopyTo().
776 void CopyTo(ServiceDescriptorProto* proto) const;
778 // See Descriptor::DebugString().
779 string DebugString() const;
781 // Source Location ---------------------------------------------------
783 // Updates |*out_location| to the source location of the complete
784 // extent of this service declaration. Returns false and leaves
785 // |*out_location| unchanged iff location information was not available.
786 bool GetSourceLocation(SourceLocation* out_location) const;
789 typedef ServiceOptions OptionsType;
791 // See Descriptor::DebugString().
792 void DebugString(string *contents) const;
794 // Walks up the descriptor tree to generate the source location path
795 // to this descriptor from the file root.
796 void GetLocationPath(vector<int>* output) const;
799 const string* full_name_;
800 const FileDescriptor* file_;
801 const ServiceOptions* options_;
803 MethodDescriptor* methods_;
804 // IMPORTANT: If you add a new field, make sure to search for all instances
805 // of Allocate<ServiceDescriptor>() and AllocateArray<ServiceDescriptor>() in
806 // descriptor.cc and update them to initialize the field.
808 // Must be constructed using DescriptorPool.
809 ServiceDescriptor() {}
810 friend class DescriptorBuilder;
811 friend class FileDescriptor;
812 friend class MethodDescriptor;
813 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ServiceDescriptor);
816 // Describes an individual service method. To obtain a MethodDescriptor given
817 // a service, first get its ServiceDescriptor, then call
818 // ServiceDescriptor::FindMethodByName(). Use DescriptorPool to construct your
820 class LIBPROTOBUF_EXPORT MethodDescriptor {
822 // Name of this method, not including containing scope.
823 const string& name() const;
824 // The fully-qualified name of the method, scope delimited by periods.
825 const string& full_name() const;
826 // Index within the service's Descriptor.
829 // Gets the service to which this method belongs. Never NULL.
830 const ServiceDescriptor* service() const;
832 // Gets the type of protocol message which this method accepts as input.
833 const Descriptor* input_type() const;
834 // Gets the type of protocol message which this message produces as output.
835 const Descriptor* output_type() const;
837 // Get options for this method. These are specified in the .proto file by
838 // placing lines like "option foo = 1234;" in curly-braces after a method
839 // declaration. Allowed options are defined by MethodOptions in
840 // google/protobuf/descriptor.proto, and any available extensions of that
842 const MethodOptions& options() const;
844 // See Descriptor::CopyTo().
845 void CopyTo(MethodDescriptorProto* proto) const;
847 // See Descriptor::DebugString().
848 string DebugString() const;
850 // Source Location ---------------------------------------------------
852 // Updates |*out_location| to the source location of the complete
853 // extent of this method declaration. Returns false and leaves
854 // |*out_location| unchanged iff location information was not available.
855 bool GetSourceLocation(SourceLocation* out_location) const;
858 typedef MethodOptions OptionsType;
860 // See Descriptor::DebugString().
861 void DebugString(int depth, string *contents) const;
863 // Walks up the descriptor tree to generate the source location path
864 // to this descriptor from the file root.
865 void GetLocationPath(vector<int>* output) const;
868 const string* full_name_;
869 const ServiceDescriptor* service_;
870 const Descriptor* input_type_;
871 const Descriptor* output_type_;
872 const MethodOptions* options_;
873 // IMPORTANT: If you add a new field, make sure to search for all instances
874 // of Allocate<MethodDescriptor>() and AllocateArray<MethodDescriptor>() in
875 // descriptor.cc and update them to initialize the field.
877 // Must be constructed using DescriptorPool.
878 MethodDescriptor() {}
879 friend class DescriptorBuilder;
880 friend class ServiceDescriptor;
881 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(MethodDescriptor);
885 // Describes a whole .proto file. To get the FileDescriptor for a compiled-in
886 // file, get the descriptor for something defined in that file and call
887 // descriptor->file(). Use DescriptorPool to construct your own descriptors.
888 class LIBPROTOBUF_EXPORT FileDescriptor {
890 // The filename, relative to the source tree.
891 // e.g. "google/protobuf/descriptor.proto"
892 const string& name() const;
894 // The package, e.g. "google.protobuf.compiler".
895 const string& package() const;
897 // The DescriptorPool in which this FileDescriptor and all its contents were
898 // allocated. Never NULL.
899 const DescriptorPool* pool() const;
901 // The number of files imported by this one.
902 int dependency_count() const;
903 // Gets an imported file by index, where 0 <= index < dependency_count().
904 // These are returned in the order they were defined in the .proto file.
905 const FileDescriptor* dependency(int index) const;
907 // The number of files public imported by this one.
908 // The public dependency list is a subset of the dependency list.
909 int public_dependency_count() const;
910 // Gets a public imported file by index, where 0 <= index <
911 // public_dependency_count().
912 // These are returned in the order they were defined in the .proto file.
913 const FileDescriptor* public_dependency(int index) const;
915 // The number of files that are imported for weak fields.
916 // The weak dependency list is a subset of the dependency list.
917 int weak_dependency_count() const;
918 // Gets a weak imported file by index, where 0 <= index <
919 // weak_dependency_count().
920 // These are returned in the order they were defined in the .proto file.
921 const FileDescriptor* weak_dependency(int index) const;
923 // Number of top-level message types defined in this file. (This does not
924 // include nested types.)
925 int message_type_count() const;
926 // Gets a top-level message type, where 0 <= index < message_type_count().
927 // These are returned in the order they were defined in the .proto file.
928 const Descriptor* message_type(int index) const;
930 // Number of top-level enum types defined in this file. (This does not
931 // include nested types.)
932 int enum_type_count() const;
933 // Gets a top-level enum type, where 0 <= index < enum_type_count().
934 // These are returned in the order they were defined in the .proto file.
935 const EnumDescriptor* enum_type(int index) const;
937 // Number of services defined in this file.
938 int service_count() const;
939 // Gets a service, where 0 <= index < service_count().
940 // These are returned in the order they were defined in the .proto file.
941 const ServiceDescriptor* service(int index) const;
943 // Number of extensions defined at file scope. (This does not include
944 // extensions nested within message types.)
945 int extension_count() const;
946 // Gets an extension's descriptor, where 0 <= index < extension_count().
947 // These are returned in the order they were defined in the .proto file.
948 const FieldDescriptor* extension(int index) const;
950 // Get options for this file. These are specified in the .proto file by
951 // placing lines like "option foo = 1234;" at the top level, outside of any
952 // other definitions. Allowed options are defined by FileOptions in
953 // google/protobuf/descriptor.proto, and any available extensions of that
955 const FileOptions& options() const;
957 // Find a top-level message type by name. Returns NULL if not found.
958 const Descriptor* FindMessageTypeByName(const string& name) const;
959 // Find a top-level enum type by name. Returns NULL if not found.
960 const EnumDescriptor* FindEnumTypeByName(const string& name) const;
961 // Find an enum value defined in any top-level enum by name. Returns NULL if
963 const EnumValueDescriptor* FindEnumValueByName(const string& name) const;
964 // Find a service definition by name. Returns NULL if not found.
965 const ServiceDescriptor* FindServiceByName(const string& name) const;
966 // Find a top-level extension definition by name. Returns NULL if not found.
967 const FieldDescriptor* FindExtensionByName(const string& name) const;
968 // Similar to FindExtensionByName(), but searches by lowercased-name. See
969 // Descriptor::FindFieldByLowercaseName().
970 const FieldDescriptor* FindExtensionByLowercaseName(const string& name) const;
971 // Similar to FindExtensionByName(), but searches by camelcased-name. See
972 // Descriptor::FindFieldByCamelcaseName().
973 const FieldDescriptor* FindExtensionByCamelcaseName(const string& name) const;
975 // See Descriptor::CopyTo().
977 // - This method does NOT copy source code information since it is relatively
978 // large and rarely needed. See CopySourceCodeInfoTo() below.
979 void CopyTo(FileDescriptorProto* proto) const;
980 // Write the source code information of this FileDescriptor into the given
981 // FileDescriptorProto. See CopyTo() above.
982 void CopySourceCodeInfoTo(FileDescriptorProto* proto) const;
984 // See Descriptor::DebugString().
985 string DebugString() const;
988 // Source Location ---------------------------------------------------
990 // Updates |*out_location| to the source location of the complete
991 // extent of the declaration or declaration-part denoted by |path|.
992 // Returns false and leaves |*out_location| unchanged iff location
993 // information was not available. (See SourceCodeInfo for
994 // description of path encoding.)
995 bool GetSourceLocation(const vector<int>& path,
996 SourceLocation* out_location) const;
998 typedef FileOptions OptionsType;
1000 const string* name_;
1001 const string* package_;
1002 const DescriptorPool* pool_;
1003 int dependency_count_;
1004 const FileDescriptor** dependencies_;
1005 int public_dependency_count_;
1006 int* public_dependencies_;
1007 int weak_dependency_count_;
1008 int* weak_dependencies_;
1009 int message_type_count_;
1010 Descriptor* message_types_;
1011 int enum_type_count_;
1012 EnumDescriptor* enum_types_;
1014 ServiceDescriptor* services_;
1015 int extension_count_;
1016 FieldDescriptor* extensions_;
1017 const FileOptions* options_;
1019 const FileDescriptorTables* tables_;
1020 const SourceCodeInfo* source_code_info_;
1021 // IMPORTANT: If you add a new field, make sure to search for all instances
1022 // of Allocate<FileDescriptor>() and AllocateArray<FileDescriptor>() in
1023 // descriptor.cc and update them to initialize the field.
1026 friend class DescriptorBuilder;
1027 friend class Descriptor;
1028 friend class FieldDescriptor;
1029 friend class EnumDescriptor;
1030 friend class EnumValueDescriptor;
1031 friend class MethodDescriptor;
1032 friend class ServiceDescriptor;
1033 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(FileDescriptor);
1036 // ===================================================================
1038 // Used to construct descriptors.
1040 // Normally you won't want to build your own descriptors. Message classes
1041 // constructed by the protocol compiler will provide them for you. However,
1042 // if you are implementing Message on your own, or if you are writing a
1043 // program which can operate on totally arbitrary types and needs to load
1044 // them from some sort of database, you might need to.
1046 // Since Descriptors are composed of a whole lot of cross-linked bits of
1047 // data that would be a pain to put together manually, the
1048 // DescriptorPool class is provided to make the process easier. It can
1049 // take a FileDescriptorProto (defined in descriptor.proto), validate it,
1050 // and convert it to a set of nicely cross-linked Descriptors.
1052 // DescriptorPool also helps with memory management. Descriptors are
1053 // composed of many objects containing static data and pointers to each
1054 // other. In all likelihood, when it comes time to delete this data,
1055 // you'll want to delete it all at once. In fact, it is not uncommon to
1056 // have a whole pool of descriptors all cross-linked with each other which
1057 // you wish to delete all at once. This class represents such a pool, and
1058 // handles the memory management for you.
1060 // You can also search for descriptors within a DescriptorPool by name, and
1061 // extensions by number.
1062 class LIBPROTOBUF_EXPORT DescriptorPool {
1064 // Create a normal, empty DescriptorPool.
1067 // Constructs a DescriptorPool that, when it can't find something among the
1068 // descriptors already in the pool, looks for it in the given
1069 // DescriptorDatabase.
1071 // - If a DescriptorPool is constructed this way, its BuildFile*() methods
1072 // must not be called (they will assert-fail). The only way to populate
1073 // the pool with descriptors is to call the Find*By*() methods.
1074 // - The Find*By*() methods may block the calling thread if the
1075 // DescriptorDatabase blocks. This in turn means that parsing messages
1076 // may block if they need to look up extensions.
1077 // - The Find*By*() methods will use mutexes for thread-safety, thus making
1078 // them slower even when they don't have to fall back to the database.
1079 // In fact, even the Find*By*() methods of descriptor objects owned by
1080 // this pool will be slower, since they will have to obtain locks too.
1081 // - An ErrorCollector may optionally be given to collect validation errors
1082 // in files loaded from the database. If not given, errors will be printed
1083 // to GOOGLE_LOG(ERROR). Remember that files are built on-demand, so this
1084 // ErrorCollector may be called from any thread that calls one of the
1085 // Find*By*() methods.
1086 class ErrorCollector;
1087 explicit DescriptorPool(DescriptorDatabase* fallback_database,
1088 ErrorCollector* error_collector = NULL);
1092 // Get a pointer to the generated pool. Generated protocol message classes
1093 // which are compiled into the binary will allocate their descriptors in
1094 // this pool. Do not add your own descriptors to this pool.
1095 static const DescriptorPool* generated_pool();
1097 // Find a FileDescriptor in the pool by file name. Returns NULL if not
1099 const FileDescriptor* FindFileByName(const string& name) const;
1101 // Find the FileDescriptor in the pool which defines the given symbol.
1102 // If any of the Find*ByName() methods below would succeed, then this is
1103 // equivalent to calling that method and calling the result's file() method.
1104 // Otherwise this returns NULL.
1105 const FileDescriptor* FindFileContainingSymbol(
1106 const string& symbol_name) const;
1108 // Looking up descriptors ------------------------------------------
1109 // These find descriptors by fully-qualified name. These will find both
1110 // top-level descriptors and nested descriptors. They return NULL if not
1113 const Descriptor* FindMessageTypeByName(const string& name) const;
1114 const FieldDescriptor* FindFieldByName(const string& name) const;
1115 const FieldDescriptor* FindExtensionByName(const string& name) const;
1116 const EnumDescriptor* FindEnumTypeByName(const string& name) const;
1117 const EnumValueDescriptor* FindEnumValueByName(const string& name) const;
1118 const ServiceDescriptor* FindServiceByName(const string& name) const;
1119 const MethodDescriptor* FindMethodByName(const string& name) const;
1121 // Finds an extension of the given type by number. The extendee must be
1122 // a member of this DescriptorPool or one of its underlays.
1123 const FieldDescriptor* FindExtensionByNumber(const Descriptor* extendee,
1126 // Finds extensions of extendee. The extensions will be appended to
1127 // out in an undefined order. Only extensions defined directly in
1128 // this DescriptorPool or one of its underlays are guaranteed to be
1129 // found: extensions defined in the fallback database might not be found
1130 // depending on the database implementation.
1131 void FindAllExtensions(const Descriptor* extendee,
1132 vector<const FieldDescriptor*>* out) const;
1134 // Building descriptors --------------------------------------------
1136 // When converting a FileDescriptorProto to a FileDescriptor, various
1137 // errors might be detected in the input. The caller may handle these
1138 // programmatically by implementing an ErrorCollector.
1139 class LIBPROTOBUF_EXPORT ErrorCollector {
1141 inline ErrorCollector() {}
1142 virtual ~ErrorCollector();
1144 // These constants specify what exact part of the construct is broken.
1145 // This is useful e.g. for mapping the error back to an exact location
1146 // in a .proto file.
1147 enum ErrorLocation {
1148 NAME, // the symbol name, or the package name for files
1149 NUMBER, // field or extension range number
1151 EXTENDEE, // field extendee
1152 DEFAULT_VALUE, // field default value
1153 INPUT_TYPE, // method input type
1154 OUTPUT_TYPE, // method output type
1155 OPTION_NAME, // name in assignment
1156 OPTION_VALUE, // value in option assignment
1157 OTHER // some other problem
1160 // Reports an error in the FileDescriptorProto.
1161 virtual void AddError(
1162 const string& filename, // File name in which the error occurred.
1163 const string& element_name, // Full name of the erroneous element.
1164 const Message* descriptor, // Descriptor of the erroneous element.
1165 ErrorLocation location, // One of the location constants, above.
1166 const string& message // Human-readable error message.
1170 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ErrorCollector);
1173 // Convert the FileDescriptorProto to real descriptors and place them in
1174 // this DescriptorPool. All dependencies of the file must already be in
1175 // the pool. Returns the resulting FileDescriptor, or NULL if there were
1176 // problems with the input (e.g. the message was invalid, or dependencies
1177 // were missing). Details about the errors are written to GOOGLE_LOG(ERROR).
1178 const FileDescriptor* BuildFile(const FileDescriptorProto& proto);
1180 // Same as BuildFile() except errors are sent to the given ErrorCollector.
1181 const FileDescriptor* BuildFileCollectingErrors(
1182 const FileDescriptorProto& proto,
1183 ErrorCollector* error_collector);
1185 // By default, it is an error if a FileDescriptorProto contains references
1186 // to types or other files that are not found in the DescriptorPool (or its
1187 // backing DescriptorDatabase, if any). If you call
1188 // AllowUnknownDependencies(), however, then unknown types and files
1189 // will be replaced by placeholder descriptors. This can allow you to
1190 // perform some useful operations with a .proto file even if you do not
1191 // have access to other .proto files on which it depends. However, some
1192 // heuristics must be used to fill in the gaps in information, and these
1193 // can lead to descriptors which are inaccurate. For example, the
1194 // DescriptorPool may be forced to guess whether an unknown type is a message
1195 // or an enum, as well as what package it resides in. Furthermore,
1196 // placeholder types will not be discoverable via FindMessageTypeByName()
1197 // and similar methods, which could confuse some descriptor-based algorithms.
1198 // Generally, the results of this option should only be relied upon for
1199 // debugging purposes.
1200 void AllowUnknownDependencies() { allow_unknown_ = true; }
1202 // Internal stuff --------------------------------------------------
1203 // These methods MUST NOT be called from outside the proto2 library.
1204 // These methods may contain hidden pitfalls and may be removed in a
1205 // future library version.
1207 // Create a DescriptorPool which is overlaid on top of some other pool.
1208 // If you search for a descriptor in the overlay and it is not found, the
1209 // underlay will be searched as a backup. If the underlay has its own
1210 // underlay, that will be searched next, and so on. This also means that
1211 // files built in the overlay will be cross-linked with the underlay's
1212 // descriptors if necessary. The underlay remains property of the caller;
1213 // it must remain valid for the lifetime of the newly-constructed pool.
1215 // Example: Say you want to parse a .proto file at runtime in order to use
1216 // its type with a DynamicMessage. Say this .proto file has dependencies,
1217 // but you know that all the dependencies will be things that are already
1218 // compiled into the binary. For ease of use, you'd like to load the types
1219 // right out of generated_pool() rather than have to parse redundant copies
1220 // of all these .protos and runtime. But, you don't want to add the parsed
1221 // types directly into generated_pool(): this is not allowed, and would be
1222 // bad design anyway. So, instead, you could use generated_pool() as an
1223 // underlay for a new DescriptorPool in which you add only the new file.
1225 // WARNING: Use of underlays can lead to many subtle gotchas. Instead,
1226 // try to formulate what you want to do in terms of DescriptorDatabases.
1227 explicit DescriptorPool(const DescriptorPool* underlay);
1229 // Called by generated classes at init time to add their descriptors to
1230 // generated_pool. Do NOT call this in your own code! filename must be a
1231 // permanent string (e.g. a string literal).
1232 static void InternalAddGeneratedFile(
1233 const void* encoded_file_descriptor, int size);
1236 // For internal use only: Gets a non-const pointer to the generated pool.
1237 // This is called at static-initialization time only, so thread-safety is
1238 // not a concern. If both an underlay and a fallback database are present,
1239 // the underlay takes precedence.
1240 static DescriptorPool* internal_generated_pool();
1242 // For internal use only: Changes the behavior of BuildFile() such that it
1243 // allows the file to make reference to message types declared in other files
1244 // which it did not officially declare as dependencies.
1245 void InternalDontEnforceDependencies();
1247 // For internal use only.
1248 void internal_set_underlay(const DescriptorPool* underlay) {
1249 underlay_ = underlay;
1252 // For internal (unit test) use only: Returns true if a FileDescriptor has
1253 // been constructed for the given file, false otherwise. Useful for testing
1254 // lazy descriptor initialization behavior.
1255 bool InternalIsFileLoaded(const string& filename) const;
1258 friend class Descriptor;
1259 friend class FieldDescriptor;
1260 friend class EnumDescriptor;
1261 friend class ServiceDescriptor;
1262 friend class FileDescriptor;
1263 friend class DescriptorBuilder;
1265 // Return true if the given name is a sub-symbol of any non-package
1266 // descriptor that already exists in the descriptor pool. (The full
1267 // definition of such types is already known.)
1268 bool IsSubSymbolOfBuiltType(const string& name) const;
1270 // Tries to find something in the fallback database and link in the
1271 // corresponding proto file. Returns true if successful, in which case
1272 // the caller should search for the thing again. These are declared
1273 // const because they are called by (semantically) const methods.
1274 bool TryFindFileInFallbackDatabase(const string& name) const;
1275 bool TryFindSymbolInFallbackDatabase(const string& name) const;
1276 bool TryFindExtensionInFallbackDatabase(const Descriptor* containing_type,
1277 int field_number) const;
1279 // Like BuildFile() but called internally when the file has been loaded from
1280 // fallback_database_. Declared const because it is called by (semantically)
1282 const FileDescriptor* BuildFileFromDatabase(
1283 const FileDescriptorProto& proto) const;
1285 // If fallback_database_ is NULL, this is NULL. Otherwise, this is a mutex
1286 // which must be locked while accessing tables_.
1290 DescriptorDatabase* fallback_database_;
1291 ErrorCollector* default_error_collector_;
1292 const DescriptorPool* underlay_;
1294 // This class contains a lot of hash maps with complicated types that
1295 // we'd like to keep out of the header.
1297 scoped_ptr<Tables> tables_;
1299 bool enforce_dependencies_;
1300 bool allow_unknown_;
1302 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(DescriptorPool);
1305 // inline methods ====================================================
1307 // These macros makes this repetitive code more readable.
1308 #define PROTOBUF_DEFINE_ACCESSOR(CLASS, FIELD, TYPE) \
1309 inline TYPE CLASS::FIELD() const { return FIELD##_; }
1311 // Strings fields are stored as pointers but returned as const references.
1312 #define PROTOBUF_DEFINE_STRING_ACCESSOR(CLASS, FIELD) \
1313 inline const string& CLASS::FIELD() const { return *FIELD##_; }
1315 // Arrays take an index parameter, obviously.
1316 #define PROTOBUF_DEFINE_ARRAY_ACCESSOR(CLASS, FIELD, TYPE) \
1317 inline TYPE CLASS::FIELD(int index) const { return FIELD##s_ + index; }
1319 #define PROTOBUF_DEFINE_OPTIONS_ACCESSOR(CLASS, TYPE) \
1320 inline const TYPE& CLASS::options() const { return *options_; }
1322 PROTOBUF_DEFINE_STRING_ACCESSOR(Descriptor, name)
1323 PROTOBUF_DEFINE_STRING_ACCESSOR(Descriptor, full_name)
1324 PROTOBUF_DEFINE_ACCESSOR(Descriptor, file, const FileDescriptor*)
1325 PROTOBUF_DEFINE_ACCESSOR(Descriptor, containing_type, const Descriptor*)
1327 PROTOBUF_DEFINE_ACCESSOR(Descriptor, field_count, int)
1328 PROTOBUF_DEFINE_ACCESSOR(Descriptor, nested_type_count, int)
1329 PROTOBUF_DEFINE_ACCESSOR(Descriptor, enum_type_count, int)
1331 PROTOBUF_DEFINE_ARRAY_ACCESSOR(Descriptor, field, const FieldDescriptor*)
1332 PROTOBUF_DEFINE_ARRAY_ACCESSOR(Descriptor, nested_type, const Descriptor*)
1333 PROTOBUF_DEFINE_ARRAY_ACCESSOR(Descriptor, enum_type, const EnumDescriptor*)
1335 PROTOBUF_DEFINE_ACCESSOR(Descriptor, extension_range_count, int)
1336 PROTOBUF_DEFINE_ACCESSOR(Descriptor, extension_count, int)
1337 PROTOBUF_DEFINE_ARRAY_ACCESSOR(Descriptor, extension_range,
1338 const Descriptor::ExtensionRange*)
1339 PROTOBUF_DEFINE_ARRAY_ACCESSOR(Descriptor, extension,
1340 const FieldDescriptor*)
1341 PROTOBUF_DEFINE_OPTIONS_ACCESSOR(Descriptor, MessageOptions)
1343 PROTOBUF_DEFINE_STRING_ACCESSOR(FieldDescriptor, name)
1344 PROTOBUF_DEFINE_STRING_ACCESSOR(FieldDescriptor, full_name)
1345 PROTOBUF_DEFINE_STRING_ACCESSOR(FieldDescriptor, lowercase_name)
1346 PROTOBUF_DEFINE_STRING_ACCESSOR(FieldDescriptor, camelcase_name)
1347 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, file, const FileDescriptor*)
1348 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, number, int)
1349 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, is_extension, bool)
1350 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, type, FieldDescriptor::Type)
1351 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, label, FieldDescriptor::Label)
1352 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, containing_type, const Descriptor*)
1353 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, extension_scope, const Descriptor*)
1354 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, message_type, const Descriptor*)
1355 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, enum_type, const EnumDescriptor*)
1356 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, experimental_map_key,
1357 const FieldDescriptor*)
1358 PROTOBUF_DEFINE_OPTIONS_ACCESSOR(FieldDescriptor, FieldOptions)
1359 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, has_default_value, bool)
1360 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, default_value_int32 , int32 )
1361 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, default_value_int64 , int64 )
1362 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, default_value_uint32, uint32)
1363 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, default_value_uint64, uint64)
1364 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, default_value_float , float )
1365 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, default_value_double, double)
1366 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, default_value_bool , bool )
1367 PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, default_value_enum,
1368 const EnumValueDescriptor*)
1369 PROTOBUF_DEFINE_STRING_ACCESSOR(FieldDescriptor, default_value_string)
1371 PROTOBUF_DEFINE_STRING_ACCESSOR(EnumDescriptor, name)
1372 PROTOBUF_DEFINE_STRING_ACCESSOR(EnumDescriptor, full_name)
1373 PROTOBUF_DEFINE_ACCESSOR(EnumDescriptor, file, const FileDescriptor*)
1374 PROTOBUF_DEFINE_ACCESSOR(EnumDescriptor, containing_type, const Descriptor*)
1375 PROTOBUF_DEFINE_ACCESSOR(EnumDescriptor, value_count, int)
1376 PROTOBUF_DEFINE_ARRAY_ACCESSOR(EnumDescriptor, value,
1377 const EnumValueDescriptor*)
1378 PROTOBUF_DEFINE_OPTIONS_ACCESSOR(EnumDescriptor, EnumOptions)
1380 PROTOBUF_DEFINE_STRING_ACCESSOR(EnumValueDescriptor, name)
1381 PROTOBUF_DEFINE_STRING_ACCESSOR(EnumValueDescriptor, full_name)
1382 PROTOBUF_DEFINE_ACCESSOR(EnumValueDescriptor, number, int)
1383 PROTOBUF_DEFINE_ACCESSOR(EnumValueDescriptor, type, const EnumDescriptor*)
1384 PROTOBUF_DEFINE_OPTIONS_ACCESSOR(EnumValueDescriptor, EnumValueOptions)
1386 PROTOBUF_DEFINE_STRING_ACCESSOR(ServiceDescriptor, name)
1387 PROTOBUF_DEFINE_STRING_ACCESSOR(ServiceDescriptor, full_name)
1388 PROTOBUF_DEFINE_ACCESSOR(ServiceDescriptor, file, const FileDescriptor*)
1389 PROTOBUF_DEFINE_ACCESSOR(ServiceDescriptor, method_count, int)
1390 PROTOBUF_DEFINE_ARRAY_ACCESSOR(ServiceDescriptor, method,
1391 const MethodDescriptor*)
1392 PROTOBUF_DEFINE_OPTIONS_ACCESSOR(ServiceDescriptor, ServiceOptions)
1394 PROTOBUF_DEFINE_STRING_ACCESSOR(MethodDescriptor, name)
1395 PROTOBUF_DEFINE_STRING_ACCESSOR(MethodDescriptor, full_name)
1396 PROTOBUF_DEFINE_ACCESSOR(MethodDescriptor, service, const ServiceDescriptor*)
1397 PROTOBUF_DEFINE_ACCESSOR(MethodDescriptor, input_type, const Descriptor*)
1398 PROTOBUF_DEFINE_ACCESSOR(MethodDescriptor, output_type, const Descriptor*)
1399 PROTOBUF_DEFINE_OPTIONS_ACCESSOR(MethodDescriptor, MethodOptions)
1400 PROTOBUF_DEFINE_STRING_ACCESSOR(FileDescriptor, name)
1401 PROTOBUF_DEFINE_STRING_ACCESSOR(FileDescriptor, package)
1402 PROTOBUF_DEFINE_ACCESSOR(FileDescriptor, pool, const DescriptorPool*)
1403 PROTOBUF_DEFINE_ACCESSOR(FileDescriptor, dependency_count, int)
1404 PROTOBUF_DEFINE_ACCESSOR(FileDescriptor, public_dependency_count, int)
1405 PROTOBUF_DEFINE_ACCESSOR(FileDescriptor, weak_dependency_count, int)
1406 PROTOBUF_DEFINE_ACCESSOR(FileDescriptor, message_type_count, int)
1407 PROTOBUF_DEFINE_ACCESSOR(FileDescriptor, enum_type_count, int)
1408 PROTOBUF_DEFINE_ACCESSOR(FileDescriptor, service_count, int)
1409 PROTOBUF_DEFINE_ACCESSOR(FileDescriptor, extension_count, int)
1410 PROTOBUF_DEFINE_OPTIONS_ACCESSOR(FileDescriptor, FileOptions)
1412 PROTOBUF_DEFINE_ARRAY_ACCESSOR(FileDescriptor, message_type, const Descriptor*)
1413 PROTOBUF_DEFINE_ARRAY_ACCESSOR(FileDescriptor, enum_type, const EnumDescriptor*)
1414 PROTOBUF_DEFINE_ARRAY_ACCESSOR(FileDescriptor, service,
1415 const ServiceDescriptor*)
1416 PROTOBUF_DEFINE_ARRAY_ACCESSOR(FileDescriptor, extension,
1417 const FieldDescriptor*)
1419 #undef PROTOBUF_DEFINE_ACCESSOR
1420 #undef PROTOBUF_DEFINE_STRING_ACCESSOR
1421 #undef PROTOBUF_DEFINE_ARRAY_ACCESSOR
1423 // A few accessors differ from the macros...
1425 inline bool FieldDescriptor::is_required() const {
1426 return label() == LABEL_REQUIRED;
1429 inline bool FieldDescriptor::is_optional() const {
1430 return label() == LABEL_OPTIONAL;
1433 inline bool FieldDescriptor::is_repeated() const {
1434 return label() == LABEL_REPEATED;
1437 inline bool FieldDescriptor::is_packable() const {
1438 return is_repeated() && IsTypePackable(type());
1441 // To save space, index() is computed by looking at the descriptor's position
1442 // in the parent's array of children.
1443 inline int FieldDescriptor::index() const {
1444 if (!is_extension_) {
1445 return this - containing_type_->fields_;
1446 } else if (extension_scope_ != NULL) {
1447 return this - extension_scope_->extensions_;
1449 return this - file_->extensions_;
1453 inline int Descriptor::index() const {
1454 if (containing_type_ == NULL) {
1455 return this - file_->message_types_;
1457 return this - containing_type_->nested_types_;
1461 inline int EnumDescriptor::index() const {
1462 if (containing_type_ == NULL) {
1463 return this - file_->enum_types_;
1465 return this - containing_type_->enum_types_;
1469 inline int EnumValueDescriptor::index() const {
1470 return this - type_->values_;
1473 inline int ServiceDescriptor::index() const {
1474 return this - file_->services_;
1477 inline int MethodDescriptor::index() const {
1478 return this - service_->methods_;
1481 inline const char* FieldDescriptor::type_name() const {
1482 return kTypeToName[type_];
1485 inline FieldDescriptor::CppType FieldDescriptor::cpp_type() const {
1486 return kTypeToCppTypeMap[type_];
1489 inline const char* FieldDescriptor::cpp_type_name() const {
1490 return kCppTypeToName[kTypeToCppTypeMap[type_]];
1493 inline FieldDescriptor::CppType FieldDescriptor::TypeToCppType(Type type) {
1494 return kTypeToCppTypeMap[type];
1497 inline bool FieldDescriptor::IsTypePackable(Type field_type) {
1498 return (field_type != FieldDescriptor::TYPE_STRING &&
1499 field_type != FieldDescriptor::TYPE_GROUP &&
1500 field_type != FieldDescriptor::TYPE_MESSAGE &&
1501 field_type != FieldDescriptor::TYPE_BYTES);
1504 inline const FileDescriptor* FileDescriptor::dependency(int index) const {
1505 return dependencies_[index];
1508 inline const FileDescriptor* FileDescriptor::public_dependency(
1510 return dependencies_[public_dependencies_[index]];
1513 inline const FileDescriptor* FileDescriptor::weak_dependency(
1515 return dependencies_[weak_dependencies_[index]];
1518 } // namespace protobuf
1520 } // namespace google
1521 #endif // GOOGLE_PROTOBUF_DESCRIPTOR_H__