1
// Protocol Buffers - Google's data interchange format
2
// Copyright 2008 Google Inc.
3
// http://code.google.com/p/protobuf/
5
// Licensed under the Apache License, Version 2.0 (the "License");
6
// you may not use this file except in compliance with the License.
7
// You may obtain a copy of the License at
9
// http://www.apache.org/licenses/LICENSE-2.0
11
// Unless required by applicable law or agreed to in writing, software
12
// distributed under the License is distributed on an "AS IS" BASIS,
13
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
// See the License for the specific language governing permissions and
15
// limitations under the License.
17
// Author: kenton@google.com (Kenton Varda)
18
// Based on original Protocol Buffers design by
19
// Sanjay Ghemawat, Jeff Dean, and others.
21
// This file contains classes which describe a type of protocol message.
22
// You can use a message's descriptor to learn at runtime what fields
23
// it contains and what the types of those fields are. The Message
24
// interface also allows you to dynamically access and modify individual
25
// fields by passing the FieldDescriptor of the field you are interested
28
// Most users will not care about descriptors, because they will write
29
// code specific to certain protocol types and will simply use the classes
30
// generated by the protocol compiler directly. Advanced users who want
31
// to operate on arbitrary types (not known at compile time) may want to
32
// read descriptors in order to learn about the contents of a message.
33
// A very small number of users will want to construct their own
34
// Descriptors, either because they are implementing Message manually or
35
// because they are writing something like the protocol compiler.
37
// For an example of how you might use descriptors, see the code example
38
// at the top of message.h.
40
#ifndef GOOGLE_PROTOBUF_DESCRIPTOR_H__
41
#define GOOGLE_PROTOBUF_DESCRIPTOR_H__
44
#include <google/protobuf/stubs/common.h>
50
// Defined in this file.
52
class FieldDescriptor;
54
class EnumValueDescriptor;
55
class ServiceDescriptor;
56
class MethodDescriptor;
58
class DescriptorDatabase;
61
// Defined in descriptor.proto
62
class DescriptorProto;
63
class FieldDescriptorProto;
64
class EnumDescriptorProto;
65
class EnumValueDescriptorProto;
66
class ServiceDescriptorProto;
67
class MethodDescriptorProto;
68
class FileDescriptorProto;
72
class EnumValueOptions;
77
// Defined in message.h
80
// Defined in descriptor.cc
81
class DescriptorBuilder;
83
// Describes a type of protocol message, or a particular group within a
84
// message. To obtain the Descriptor for a given message object, call
85
// Message::GetDescriptor(). Generated message classes also have a
86
// static method called descriptor() which returns the type's descriptor.
87
// Use DescriptorPool to construct your own descriptors.
88
class LIBPROTOBUF_EXPORT Descriptor {
90
// The name of the message type, not including its scope.
91
const string& name() const;
93
// The fully-qualified name of the message type, scope delimited by
94
// periods. For example, message type "Foo" which is declared in package
95
// "bar" has full name "bar.Foo". If a type "Baz" is nested within
96
// Foo, Baz's full_name is "bar.Foo.Baz". To get only the part that
97
// comes after the last '.', use name().
98
const string& full_name() const;
100
// Index of this descriptor within the file or containing type's message
104
// The .proto file in which this message type was defined. Never NULL.
105
const FileDescriptor* file() const;
107
// If this Descriptor describes a nested type, this returns the type
108
// in which it is nested. Otherwise, returns NULL.
109
const Descriptor* containing_type() const;
111
// Get options for this message type. These are specified in the .proto
112
// file by placing lines like "option foo = 1234;" in the message definition.
113
// The exact set of known options is defined by MessageOptions in
114
// google/protobuf/descriptor.proto.
115
const MessageOptions& options() const;
117
// Write the contents of this Descriptor into the given DescriptorProto.
118
// The target DescriptorProto must be clear before calling this; if it
119
// isn't, the result may be garbage.
120
void CopyTo(DescriptorProto* proto) const;
122
// Write the contents of this decriptor in a human-readable form. Output
123
// will be suitable for re-parsing.
124
string DebugString() const;
126
// Field stuff -----------------------------------------------------
128
// The number of fields in this message type.
129
int field_count() const;
130
// Gets a field by index, where 0 <= index < field_count().
131
const FieldDescriptor* field(int index) const;
133
// Looks up a field by declared tag number. Returns NULL if no such field
135
const FieldDescriptor* FindFieldByNumber(int number) const;
136
// Looks up a field by name. Returns NULL if no such field exists.
137
const FieldDescriptor* FindFieldByName(const string& name) const;
139
// Nested type stuff -----------------------------------------------
141
// The number of nested types in this message type.
142
int nested_type_count() const;
143
// Gets a nested type by index, where 0 <= index < nested_type_count().
144
const Descriptor* nested_type(int index) const;
146
// Looks up a nested type by name. Returns NULL if no such nested type
148
const Descriptor* FindNestedTypeByName(const string& name) const;
150
// Enum stuff ------------------------------------------------------
152
// The number of enum types in this message type.
153
int enum_type_count() const;
154
// Gets an enum type by index, where 0 <= index < enum_type_count().
155
const EnumDescriptor* enum_type(int index) const;
157
// Looks up an enum type by name. Returns NULL if no such enum type exists.
158
const EnumDescriptor* FindEnumTypeByName(const string& name) const;
160
// Looks up an enum value by name, among all enum types in this message.
161
// Returns NULL if no such value exists.
162
const EnumValueDescriptor* FindEnumValueByName(const string& name) const;
164
// Extensions ------------------------------------------------------
166
// A range of field numbers which are designated for third-party
168
struct ExtensionRange {
169
int start; // inclusive
170
int end; // exclusive
173
// The number of extension ranges in this message type.
174
int extension_range_count() const;
175
// Gets an extension range by index, where 0 <= index <
176
// extension_range_count().
177
const ExtensionRange* extension_range(int index) const;
179
// Returns true if the number is in one of the extension ranges.
180
bool IsExtensionNumber(int number) const;
182
// The number of extensions -- extending *other* messages -- that were
183
// defined nested within this message type's scope.
184
int extension_count() const;
185
// Get an extension by index, where 0 <= index < extension_count().
186
const FieldDescriptor* extension(int index) const;
188
// Looks up a named extension (which extends some *other* message type)
189
// defined within this message type's scope.
190
const FieldDescriptor* FindExtensionByName(const string& name) const;
193
// Internal version of DebugString; controls the level of indenting for
195
void DebugString(int depth, string *contents) const;
198
const string* full_name_;
199
const FileDescriptor* file_;
200
const Descriptor* containing_type_;
201
const MessageOptions* options_;
203
FieldDescriptor* fields_;
204
int nested_type_count_;
205
Descriptor* nested_types_;
206
int enum_type_count_;
207
EnumDescriptor* enum_types_;
208
int extension_range_count_;
209
ExtensionRange* extension_ranges_;
210
int extension_count_;
211
FieldDescriptor* extensions_;
213
// Must be constructed using DescriptorPool.
215
friend class DescriptorBuilder;
216
friend class EnumDescriptor;
217
friend class FieldDescriptor;
218
friend class FileDescriptor;
219
GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(Descriptor);
222
// Describes a single field of a message. To get the descriptor for a given
223
// field, first get the Descriptor for the message in which it is defined,
224
// then call Descriptor::FindFieldByName(). To get a FieldDescriptor for
225
// an extension, do one of the following:
226
// - Get the Descriptor or FileDescriptor for its containing scope, then
227
// call Descriptor::FindExtensionByName() or
228
// FileDescriptor::FindExtensionByName().
229
// - Given a DescriptorPool, call DescriptorPool::FindExtensionByNumber().
230
// - Given a Message::Reflection for a message object, call
231
// Message::Reflection::FindKnownExtensionByName() or
232
// Message::Reflection::FindKnownExtensionByNumber().
233
// Use DescriptorPool to construct your own descriptors.
234
class LIBPROTOBUF_EXPORT FieldDescriptor {
236
// Identifies a field type. 0 is reserved for errors. The order is weird
237
// for historical reasons. Types 12 and up are new in proto2.
239
TYPE_DOUBLE = 1, // double, exactly eight bytes on the wire.
240
TYPE_FLOAT = 2, // float, exactly four bytes on the wire.
241
TYPE_INT64 = 3, // int64, varint on the wire. Negative numbers
242
// take 10 bytes. Use TYPE_SINT64 if negative
243
// values are likely.
244
TYPE_UINT64 = 4, // uint64, varint on the wire.
245
TYPE_INT32 = 5, // int32, varint on the wire. Negative numbers
246
// take 10 bytes. Use TYPE_SINT32 if negative
247
// values are likely.
248
TYPE_FIXED64 = 6, // uint64, exactly eight bytes on the wire.
249
TYPE_FIXED32 = 7, // uint32, exactly four bytes on the wire.
250
TYPE_BOOL = 8, // bool, varint on the wire.
251
TYPE_STRING = 9, // UTF-8 text.
252
TYPE_GROUP = 10, // Tag-delimited message. Deprecated.
253
TYPE_MESSAGE = 11, // Length-delimited message.
255
TYPE_BYTES = 12, // Arbitrary byte array.
256
TYPE_UINT32 = 13, // uint32, varint on the wire
257
TYPE_ENUM = 14, // Enum, varint on the wire
258
TYPE_SFIXED32 = 15, // int32, exactly four bytes on the wire
259
TYPE_SFIXED64 = 16, // int64, exactly eight bytes on the wire
260
TYPE_SINT32 = 17, // int32, ZigZag-encoded varint on the wire
261
TYPE_SINT64 = 18, // int64, ZigZag-encoded varint on the wire
263
MAX_TYPE = 18, // Constant useful for defining lookup tables
267
// Specifies the C++ data type used to represent the field. There is a
268
// fixed mapping from Type to CppType where each Type maps to exactly one
269
// CppType. 0 is reserved for errors.
271
CPPTYPE_INT32 = 1, // TYPE_INT32, TYPE_SINT32, TYPE_SFIXED32
272
CPPTYPE_INT64 = 2, // TYPE_INT64, TYPE_SINT64, TYPE_SFIXED64
273
CPPTYPE_UINT32 = 3, // TYPE_UINT32, TYPE_FIXED32
274
CPPTYPE_UINT64 = 4, // TYPE_UINT64, TYPE_FIXED64
275
CPPTYPE_DOUBLE = 5, // TYPE_DOUBLE
276
CPPTYPE_FLOAT = 6, // TYPE_FLOAT
277
CPPTYPE_BOOL = 7, // TYPE_BOOL
278
CPPTYPE_ENUM = 8, // TYPE_ENUM
279
CPPTYPE_STRING = 9, // TYPE_STRING, TYPE_BYTES
280
CPPTYPE_MESSAGE = 10, // TYPE_MESSAGE, TYPE_GROUP
282
MAX_CPPTYPE = 10, // Constant useful for defining lookup tables
283
// indexed by CppType.
286
// Identifies whether the field is optional, required, or repeated. 0 is
287
// reserved for errors.
289
LABEL_OPTIONAL = 1, // optional
290
LABEL_REQUIRED = 2, // required
291
LABEL_REPEATED = 3, // repeated
293
MAX_LABEL = 3, // Constant useful for defining lookup tables
297
// Valid field numbers are positive integers up to kMaxNumber.
298
static const int kMaxNumber = (1 << 29) - 1;
300
// First field number reserved for the protocol buffer library implementation.
301
// Users may not declare fields that use reserved numbers.
302
static const int kFirstReservedNumber = 19000;
303
// Last field number reserved for the protocol buffer library implementation.
304
// Users may not declare fields that use reserved numbers.
305
static const int kLastReservedNumber = 19999;
307
const string& name() const; // Name of this field within the message.
308
const string& full_name() const; // Fully-qualified name of the field.
309
const FileDescriptor* file() const;// File in which this field was defined.
310
bool is_extension() const; // Is this an extension field?
311
int number() const; // Declared tag number.
313
Type type() const; // Declared type of this field.
314
CppType cpp_type() const; // C++ type of this field.
315
Label label() const; // optional/required/repeated
317
bool is_required() const; // shorthand for label() == LABEL_REQUIRED
318
bool is_optional() const; // shorthand for label() == LABEL_OPTIONAL
319
bool is_repeated() const; // shorthand for label() == LABEL_REPEATED
321
// Index of this field within the message's field array, or the file or
322
// extension scope's extensions array.
325
// Does this field have an explicitly-declared default value?
326
bool has_default_value() const;
328
// Get the field default value if cpp_type() == CPPTYPE_INT32. If no
329
// explicit default was defined, the default is 0.
330
int32 default_value_int32() const;
331
// Get the field default value if cpp_type() == CPPTYPE_INT64. If no
332
// explicit default was defined, the default is 0.
333
int64 default_value_int64() const;
334
// Get the field default value if cpp_type() == CPPTYPE_UINT32. If no
335
// explicit default was defined, the default is 0.
336
uint32 default_value_uint32() const;
337
// Get the field default value if cpp_type() == CPPTYPE_UINT64. If no
338
// explicit default was defined, the default is 0.
339
uint64 default_value_uint64() const;
340
// Get the field default value if cpp_type() == CPPTYPE_FLOAT. If no
341
// explicit default was defined, the default is 0.0.
342
float default_value_float() const;
343
// Get the field default value if cpp_type() == CPPTYPE_DOUBLE. If no
344
// explicit default was defined, the default is 0.0.
345
double default_value_double() const;
346
// Get the field default value if cpp_type() == CPPTYPE_BOOL. If no
347
// explicit default was defined, the default is false.
348
bool default_value_bool() const;
349
// Get the field default value if cpp_type() == CPPTYPE_ENUM. If no
350
// explicit default was defined, the default is the first value defined
351
// in the enum type (all enum types are required to have at least one value).
352
// This never returns NULL.
353
const EnumValueDescriptor* default_value_enum() const;
354
// Get the field default value if cpp_type() == CPPTYPE_STRING. If no
355
// explicit default was defined, the default is the empty string.
356
const string& default_value_string() const;
358
// The Descriptor for the message of which this is a field. For extensions,
359
// this is the extended type. Never NULL.
360
const Descriptor* containing_type() const;
362
// An extension may be declared within the scope of another message. If this
363
// field is an extension (is_extension() is true), then extension_scope()
364
// returns that message, or NULL if the extension was declared at global
365
// scope. If this is not an extension, extension_scope() is undefined (may
367
const Descriptor* extension_scope() const;
369
// If type is TYPE_MESSAGE or TYPE_GROUP, returns a descriptor for the
370
// message or the group type. Otherwise, undefined.
371
const Descriptor* message_type() const;
372
// If type is TYPE_ENUM, returns a descriptor for the enum. Otherwise,
374
const EnumDescriptor* enum_type() const;
376
// EXPERIMENTAL; DO NOT USE.
377
// If this field is a map field, experimental_map_key() is the field
378
// that is the key for this map.
379
// experimental_map_key()->containing_type() is the same as message_type().
380
const FieldDescriptor* experimental_map_key() const;
382
// Get the FieldOptions for this field. This includes things listed in
383
// square brackets after the field definition. E.g., the field:
384
// optional string text = 1 [ctype=CORD];
385
// has the "ctype" option set. FieldOptions is actually a protocol message,
386
// which makes it easier to extend.
387
const FieldOptions& options() const;
389
// See Descriptor::CopyTo().
390
void CopyTo(FieldDescriptorProto* proto) const;
392
// See Descriptor::DebugString().
393
string DebugString() const;
395
// See Descriptor::DebugString().
396
void DebugString(int depth, string *contents) const;
398
// formats the default value appropriately and returns it as a string.
399
// Must have a default value to call this. If quote_string_type is true, then
400
// types of CPPTYPE_STRING whill be surrounded by quotes and CEscaped.
401
string DefaultValueAsString(bool quote_string_type) const;
404
const string* full_name_;
405
const FileDescriptor* file_;
410
const Descriptor* containing_type_;
411
const Descriptor* extension_scope_;
412
const Descriptor* message_type_;
413
const EnumDescriptor* enum_type_;
414
const FieldDescriptor* experimental_map_key_;
415
const FieldOptions* options_;
417
bool has_default_value_;
419
int32 default_value_int32_;
420
int64 default_value_int64_;
421
uint32 default_value_uint32_;
422
uint64 default_value_uint64_;
423
float default_value_float_;
424
double default_value_double_;
425
bool default_value_bool_;
427
const EnumValueDescriptor* default_value_enum_;
428
const string* default_value_string_;
431
static const CppType kTypeToCppTypeMap[MAX_TYPE + 1];
433
static const char * const kTypeToName[MAX_TYPE + 1];
435
static const char * const kLabelToName[MAX_LABEL + 1];
437
// Must be constructed using DescriptorPool.
439
friend class DescriptorBuilder;
440
friend class FileDescriptor;
441
friend class Descriptor;
442
GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(FieldDescriptor);
445
// Describes an enum type defined in a .proto file. To get the EnumDescriptor
446
// for a generated enum type, call TypeName_descriptor(). Use DescriptorPool
447
// to construct your own descriptors.
448
class LIBPROTOBUF_EXPORT EnumDescriptor {
450
// The name of this enum type in the containing scope.
451
const string& name() const;
453
// The fully-qualified name of the enum type, scope delimited by periods.
454
const string& full_name() const;
456
// Index of this enum within the file or containing message's enum array.
459
// The .proto file in which this enum type was defined. Never NULL.
460
const FileDescriptor* file() const;
462
// The number of values for this EnumDescriptor. Guaranteed to be greater
464
int value_count() const;
465
// Gets a value by index, where 0 <= index < value_count().
466
const EnumValueDescriptor* value(int index) const;
468
// Looks up a value by name. Returns NULL if no such value exists.
469
const EnumValueDescriptor* FindValueByName(const string& name) const;
470
// Looks up a value by number. Returns NULL if no such value exists. If
471
// multiple values have this number, the first one defined is returned.
472
const EnumValueDescriptor* FindValueByNumber(int number) const;
474
// If this enum type is nested in a message type, this is that message type.
476
const Descriptor* containing_type() const;
478
// Get options for this enum type. These are specified in the .proto
479
// file by placing lines like "option foo = 1234;" in the enum definition.
480
// The exact set of known options is defined by EnumOptions in
481
// google/protobuf/descriptor.proto.
482
const EnumOptions& options() const;
484
// See Descriptor::CopyTo().
485
void CopyTo(EnumDescriptorProto* proto) const;
487
// See Descriptor::DebugString().
488
string DebugString() const;
491
// See Descriptor::DebugString().
492
void DebugString(int depth, string *contents) const;
495
const string* full_name_;
496
const FileDescriptor* file_;
498
EnumValueDescriptor* values_;
499
const Descriptor* containing_type_;
500
const EnumOptions* options_;
502
// Must be constructed using DescriptorPool.
504
friend class DescriptorBuilder;
505
friend class Descriptor;
506
friend class EnumValueDescriptor;
507
friend class FileDescriptor;
508
GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(EnumDescriptor);
511
// Describes an individual enum constant of a particular type. To get the
512
// EnumValueDescriptor for a given enum value, first get the EnumDescriptor
513
// for its type, then use EnumDescriptor::FindValueByName() or
514
// EnumDescriptor::FindValueByNumber(). Use DescriptorPool to construct
515
// your own descriptors.
516
class LIBPROTOBUF_EXPORT EnumValueDescriptor {
518
const string& name() const; // Name of this enum constant.
519
int index() const; // Index within the enums's Descriptor.
520
int number() const; // Numeric value of this enum constant.
522
// The full_name of an enum value is a sibling symbol of the enum type.
523
// e.g. the full name of FieldDescriptorProto::TYPE_INT32 is actually
524
// "google.protobuf.FieldDescriptorProto.TYPE_INT32", NOT
525
// "google.protobuf.FieldDescriptorProto.Type.TYPE_INT32". This is to conform
526
// with C++ scoping rules for enums.
527
const string& full_name() const;
529
// The type of this value. Never NULL.
530
const EnumDescriptor* type() const;
532
// Get options for this enum value. These are specified in the .proto
533
// file by adding text like "[foo = 1234]" after an enum value definition.
534
// The exact set of known options is defined by EnumValueOptions in
535
// google/protobuf/descriptor.proto.
536
const EnumValueOptions& options() const;
538
// See Descriptor::CopyTo().
539
void CopyTo(EnumValueDescriptorProto* proto) const;
541
// See Descriptor::DebugString().
542
string DebugString() const;
545
// See Descriptor::DebugString().
546
void DebugString(int depth, string *contents) const;
549
const string* full_name_;
551
const EnumDescriptor* type_;
552
const EnumValueOptions* options_;
554
// Must be constructed using DescriptorPool.
555
EnumValueDescriptor() {}
556
friend class DescriptorBuilder;
557
friend class EnumDescriptor;
558
GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(EnumValueDescriptor);
561
// Describes an RPC service. To get the ServiceDescriptor for a service,
562
// call Service::GetDescriptor(). Generated service classes also have a
563
// static method called descriptor() which returns the type's
564
// ServiceDescriptor. Use DescriptorPool to construct your own descriptors.
565
class LIBPROTOBUF_EXPORT ServiceDescriptor {
567
// The name of the service, not including its containing scope.
568
const string& name() const;
569
// The fully-qualified name of the service, scope delimited by periods.
570
const string& full_name() const;
571
// Index of this service within the file's services array.
574
// The .proto file in which this service was defined. Never NULL.
575
const FileDescriptor* file() const;
577
// Get options for this service type. These are specified in the .proto
578
// file by placing lines like "option foo = 1234;" in the service definition.
579
// The exact set of known options is defined by ServiceOptions in
580
// google/protobuf/descriptor.proto.
581
const ServiceOptions& options() const;
583
// The number of methods this service defines.
584
int method_count() const;
585
// Gets a MethodDescriptor by index, where 0 <= index < method_count().
586
const MethodDescriptor* method(int index) const;
588
// Look up a MethodDescriptor by name.
589
const MethodDescriptor* FindMethodByName(const string& name) const;
591
// See Descriptor::CopyTo().
592
void CopyTo(ServiceDescriptorProto* proto) const;
594
// See Descriptor::DebugString().
595
string DebugString() const;
598
// See Descriptor::DebugString().
599
void DebugString(string *contents) const;
602
const string* full_name_;
603
const FileDescriptor* file_;
604
const ServiceOptions* options_;
606
MethodDescriptor* methods_;
608
// Must be constructed using DescriptorPool.
609
ServiceDescriptor() {}
610
friend class DescriptorBuilder;
611
friend class FileDescriptor;
612
friend class MethodDescriptor;
613
GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ServiceDescriptor);
616
// Describes an individual service method. To obtain a MethodDescriptor given
617
// a service, first get its ServiceDescriptor, then call
618
// ServiceDescriptor::FindMethodByName(). Use DescriptorPool to construct your
620
class LIBPROTOBUF_EXPORT MethodDescriptor {
622
// Name of this method, not including containing scope.
623
const string& name() const;
624
// The fully-qualified name of the method, scope delimited by periods.
625
const string& full_name() const;
626
// Index within the service's Descriptor.
629
// Gets the service to which this method belongs. Never NULL.
630
const ServiceDescriptor* service() const;
632
// Gets the type of protocol message which this method accepts as input.
633
const Descriptor* input_type() const;
634
// Gets the type of protocol message which this message produces as output.
635
const Descriptor* output_type() const;
637
// Get options for this method. These are specified in the .proto
638
// file by placing lines like "option foo = 1234;" in curly-braces after
639
// a method declaration. The exact set of known options is defined by
640
// MethodOptions in google/protobuf/descriptor.proto.
641
const MethodOptions& options() const;
643
// See Descriptor::CopyTo().
644
void CopyTo(MethodDescriptorProto* proto) const;
646
// See Descriptor::DebugString().
647
string DebugString() const;
650
// See Descriptor::DebugString().
651
void DebugString(int depth, string *contents) const;
654
const string* full_name_;
655
const ServiceDescriptor* service_;
656
const Descriptor* input_type_;
657
const Descriptor* output_type_;
658
const MethodOptions* options_;
660
// Must be constructed using DescriptorPool.
661
MethodDescriptor() {}
662
friend class DescriptorBuilder;
663
friend class ServiceDescriptor;
664
GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(MethodDescriptor);
667
// Describes a whole .proto file. To get the FileDescriptor for a compiled-in
668
// file, get the descriptor for something defined in that file and call
669
// descriptor->file(). Use DescriptorPool to construct your own descriptors.
670
class LIBPROTOBUF_EXPORT FileDescriptor {
672
// The filename, relative to the source tree.
673
// e.g. "google/protobuf/descriptor.proto"
674
const string& name() const;
676
// The package, e.g. "google.protobuf.compiler".
677
const string& package() const;
679
// The DescriptorPool in which this FileDescriptor and all its contents were
680
// allocated. Never NULL.
681
const DescriptorPool* pool() const;
683
// The number of files imported by this one.
684
int dependency_count() const;
685
// Gets an imported file by index, where 0 <= index < dependency_count().
686
const FileDescriptor* dependency(int index) const;
688
// Number of top-level message types defined in this file. (This does not
689
// include nested types.)
690
int message_type_count() const;
691
// Gets a top-level message type, where 0 <= index < message_type_count().
692
const Descriptor* message_type(int index) const;
694
// Number of top-level enum types defined in this file. (This does not
695
// include nested types.)
696
int enum_type_count() const;
697
// Gets a top-level enum type, where 0 <= index < enum_type_count().
698
const EnumDescriptor* enum_type(int index) const;
700
// Number of services defined in this file.
701
int service_count() const;
702
// Gets a service, where 0 <= index < service_count().
703
const ServiceDescriptor* service(int index) const;
705
// Number of extensions defined at file scope. (This does not include
706
// extensions nested within message types.)
707
int extension_count() const;
708
// Gets an extension's descriptor, where 0 <= index < extension_count().
709
const FieldDescriptor* extension(int index) const;
711
// Get options for this file. These are specified in the .proto
712
// file by placing lines like "option foo = 1234;" at the top level, outside
713
// of any other definitions. The exact set of known options is defined by
714
// FileOptions in google/protobuf/descriptor.proto.
715
const FileOptions& options() const;
717
// Find a top-level message type by name. Returns NULL if not found.
718
const Descriptor* FindMessageTypeByName(const string& name) const;
719
// Find a top-level enum type by name. Returns NULL if not found.
720
const EnumDescriptor* FindEnumTypeByName(const string& name) const;
721
// Find an enum value defined in any top-level enum by name. Returns NULL if
723
const EnumValueDescriptor* FindEnumValueByName(const string& name) const;
724
// Find a service definition by name. Returns NULL if not found.
725
const ServiceDescriptor* FindServiceByName(const string& name) const;
726
// Find a top-level extension definition by name. Returns NULL if not found.
727
const FieldDescriptor* FindExtensionByName(const string& name) const;
729
// See Descriptor::CopyTo().
730
void CopyTo(FileDescriptorProto* proto) const;
732
// See Descriptor::DebugString().
733
string DebugString() const;
737
const string* package_;
738
const DescriptorPool* pool_;
739
int dependency_count_;
740
const FileDescriptor** dependencies_;
741
int message_type_count_;
742
Descriptor* message_types_;
743
int enum_type_count_;
744
EnumDescriptor* enum_types_;
746
ServiceDescriptor* services_;
747
int extension_count_;
748
FieldDescriptor* extensions_;
749
const FileOptions* options_;
752
friend class DescriptorBuilder;
753
friend class Descriptor;
754
friend class FieldDescriptor;
755
friend class EnumDescriptor;
756
friend class ServiceDescriptor;
757
GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(FileDescriptor);
760
// ===================================================================
762
// Used to construct descriptors.
764
// Normally you won't want to build your own descriptors. Message classes
765
// constructed by the protocol compiler will provide them for you. However,
766
// if you are implementing Message on your own, or if you are writing a
767
// program which can operate on totally arbitrary types and needs to load
768
// them from some sort of database, you might need to.
770
// Since Descriptors are composed of a whole lot of cross-linked bits of
771
// data that would be a pain to put together manually, the
772
// DescriptorPool class is provided to make the process easier. It can
773
// take a FileDescriptorProto (defined in descriptor.proto), validate it,
774
// and convert it to a set of nicely cross-linked Descriptors.
776
// DescriptorPool also helps with memory management. Descriptors are
777
// composed of many objects containing static data and pointers to each
778
// other. In all likelihood, when it comes time to delete this data,
779
// you'll want to delete it all at once. In fact, it is not uncommon to
780
// have a whole pool of descriptors all cross-linked with each other which
781
// you wish to delete all at once. This class represents such a pool, and
782
// handles the memory management for you.
784
// You can also search for descriptors within a DescriptorPool by name, and
785
// extensions by number.
786
class LIBPROTOBUF_EXPORT DescriptorPool {
788
// Create a normal, empty DescriptorPool.
791
// Constructs a DescriptorPool that, when it can't find something among the
792
// descriptors already in the pool, looks for it in the given
793
// DescriptorDatabase.
795
// - If a DescriptorPool is constructed this way, its BuildFile*() methods
796
// must not be called (they will assert-fail). The only way to populate
797
// the pool with descriptors is to call the Find*By*() methods.
798
// - The Find*By*() methods may block the calling thread if the
799
// DescriptorDatabase blocks. This in turn means that parsing messages
800
// may block if they need to look up extensions.
801
// - The Find*By*() methods will use mutexes for thread-safety, thus making
802
// them slower even when they don't have to fall back to the database.
803
// In fact, even the Find*By*() methods of descriptor objects owned by
804
// this pool will be slower, since they will have to obtain locks too.
805
// - An ErrorCollector may optionally be given to collect validation errors
806
// in files loaded from the database. If not given, errors will be printed
807
// to GOOGLE_LOG(ERROR). Remember that files are built on-demand, so this
808
// ErrorCollector may be called from any thread that calls one of the
809
// Find*By*() methods.
810
class ErrorCollector;
811
explicit DescriptorPool(DescriptorDatabase* fallback_database,
812
ErrorCollector* error_collector = NULL);
816
// Get a pointer to the generated pool. Generated protocol message classes
817
// which are compiled into the binary will allocate their descriptors in
818
// this pool. Do not add your own descriptors to this pool.
819
static const DescriptorPool* generated_pool();
821
// Find a FileDescriptor in the pool by file name. Returns NULL if not
823
const FileDescriptor* FindFileByName(const string& name) const;
825
// Find the FileDescriptor in the pool which defines the given symbol.
826
// If any of the Find*ByName() methods below would succeed, then this is
827
// equivalent to calling that method and calling the result's file() method.
828
// Otherwise this returns NULL.
829
const FileDescriptor* FindFileContainingSymbol(
830
const string& symbol_name) const;
832
// Looking up descriptors ------------------------------------------
833
// These find descriptors by fully-qualified name. These will find both
834
// top-level descriptors and nested descriptors. They return NULL if not
837
const Descriptor* FindMessageTypeByName(const string& name) const;
838
const FieldDescriptor* FindFieldByName(const string& name) const;
839
const FieldDescriptor* FindExtensionByName(const string& name) const;
840
const EnumDescriptor* FindEnumTypeByName(const string& name) const;
841
const EnumValueDescriptor* FindEnumValueByName(const string& name) const;
842
const ServiceDescriptor* FindServiceByName(const string& name) const;
843
const MethodDescriptor* FindMethodByName(const string& name) const;
845
// Finds an extension of the given type by number. The extendee must be
846
// a member of this DescriptorPool or one of its underlays.
847
const FieldDescriptor* FindExtensionByNumber(const Descriptor* extendee,
850
// Building descriptors --------------------------------------------
852
// When converting a FileDescriptorProto to a FileDescriptor, various
853
// errors might be detected in the input. The caller may handle these
854
// programmatically by implementing an ErrorCollector.
855
class LIBPROTOBUF_EXPORT ErrorCollector {
857
inline ErrorCollector() {}
858
virtual ~ErrorCollector();
860
// These constants specify what exact part of the construct is broken.
861
// This is useful e.g. for mapping the error back to an exact location
864
NAME, // the symbol name, or the package name for files
865
NUMBER, // field or extension range number
867
EXTENDEE, // field extendee
868
DEFAULT_VALUE, // field default value
869
INPUT_TYPE, // method input type
870
OUTPUT_TYPE, // method output type
871
OTHER // some other problem
874
// Reports an error in the FileDescriptorProto.
875
virtual void AddError(
876
const string& filename, // File name in which the error occurred.
877
const string& element_name, // Full name of the erroneous element.
878
const Message* descriptor, // Descriptor of the erroneous element.
879
ErrorLocation location, // One of the location constants, above.
880
const string& message // Human-readable error message.
884
GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ErrorCollector);
887
// Convert the FileDescriptorProto to real descriptors and place them in
888
// this DescriptorPool. All dependencies of the file must already be in
889
// the pool. Returns the resulting FileDescriptor, or NULL if there were
890
// problems with the input (e.g. the message was invalid, or dependencies
891
// were missing). Details about the errors are written to GOOGLE_LOG(ERROR).
892
const FileDescriptor* BuildFile(const FileDescriptorProto& proto);
894
// Same as BuildFile() except errors are sent to the given ErrorCollector.
895
const FileDescriptor* BuildFileCollectingErrors(
896
const FileDescriptorProto& proto,
897
ErrorCollector* error_collector);
899
// Internal stuff --------------------------------------------------
900
// These methods MUST NOT be called from outside the proto2 library.
901
// These methods may contain hidden pitfalls and may be removed in a
902
// future library version.
904
// DEPRECATED: Use of underlays can lead to many subtle gotchas. Instead,
905
// try to formulate what you want to do in terms of DescriptorDatabases.
906
// This constructor will be removed soon.
908
// Create a DescriptorPool which is overlaid on top of some other pool.
909
// If you search for a descriptor in the overlay and it is not found, the
910
// underlay will be searched as a backup. If the underlay has its own
911
// underlay, that will be searched next, and so on. This also means that
912
// files built in the overlay will be cross-linked with the underlay's
913
// descriptors if necessary. The underlay remains property of the caller;
914
// it must remain valid for the lifetime of the newly-constructed pool.
916
// Example: Say you want to parse a .proto file at runtime in order to use
917
// its type with a DynamicMessage. Say this .proto file has dependencies,
918
// but you know that all the dependencies will be things that are already
919
// compiled into the binary. For ease of use, you'd like to load the types
920
// right out of generated_pool() rather than have to parse redundant copies
921
// of all these .protos and runtime. But, you don't want to add the parsed
922
// types directly into generated_pool(): this is not allowed, and would be
923
// bad design anyway. So, instead, you could use generated_pool() as an
924
// underlay for a new DescriptorPool in which you add only the new file.
925
explicit DescriptorPool(const DescriptorPool* underlay);
927
// Called by generated classes at init time. Do NOT call this in your
929
const FileDescriptor* InternalBuildGeneratedFile(
930
const void* data, int size);
932
// For internal use only: Gets a non-const pointer to the generated pool.
933
// This is called at static-initialization time only, so thread-safety is
934
// not a concern. If both an underlay and a fallback database are present,
935
// the fallback database takes precedence.
936
static DescriptorPool* internal_generated_pool();
938
// For internal use only: Changes the behavior of BuildFile() such that it
939
// allows the file to make reference to message types declared in other files
940
// which it did not officially declare as dependencies.
941
void InternalDontEnforceDependencies();
943
// For internal use only.
944
void internal_set_underlay(const DescriptorPool* underlay) {
945
underlay_ = underlay;
949
friend class Descriptor;
950
friend class FieldDescriptor;
951
friend class EnumDescriptor;
952
friend class ServiceDescriptor;
953
friend class FileDescriptor;
954
friend class DescriptorBuilder;
956
// Tries to find something in the fallback database and link in the
957
// corresponding proto file. Returns true if successful, in which case
958
// the caller should search for the thing again. These are declared
959
// const because they are called by (semantically) const methods.
960
bool TryFindFileInFallbackDatabase(const string& name) const;
961
bool TryFindSymbolInFallbackDatabase(const string& name) const;
962
bool TryFindExtensionInFallbackDatabase(const Descriptor* containing_type,
963
int field_number) const;
965
// Like BuildFile() but called internally when the file has been loaded from
966
// fallback_database_. Declared const because it is called by (semantically)
968
const FileDescriptor* BuildFileFromDatabase(
969
const FileDescriptorProto& proto) const;
971
// If fallback_database_ is NULL, this is NULL. Otherwise, this is a mutex
972
// which must be locked while accessing tables_.
976
DescriptorDatabase* fallback_database_;
977
ErrorCollector* default_error_collector_;
978
const DescriptorPool* underlay_;
980
// This class contains a lot of hash maps with complicated types that
981
// we'd like to keep out of the header.
983
scoped_ptr<Tables> tables_;
985
bool enforce_dependencies_;
987
// See InternalBuildGeneratedFile().
988
const void* last_internal_build_generated_file_call_;
990
GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(DescriptorPool);
993
// inline methods ====================================================
995
// These macros makes this repetitive code more readable.
996
#define PROTOBUF_DEFINE_ACCESSOR(CLASS, FIELD, TYPE) \
997
inline TYPE CLASS::FIELD() const { return FIELD##_; }
999
// Strings fields are stored as pointers but returned as const references.
1000
#define PROTOBUF_DEFINE_STRING_ACCESSOR(CLASS, FIELD) \
1001
inline const string& CLASS::FIELD() const { return *FIELD##_; }
1003
// Arrays take an index parameter, obviously.
1004
#define PROTOBUF_DEFINE_ARRAY_ACCESSOR(CLASS, FIELD, TYPE) \
1005
inline TYPE CLASS::FIELD(int index) const { return FIELD##s_ + index; }
1007
#define PROTOBUF_DEFINE_OPTIONS_ACCESSOR(CLASS, TYPE) \
1008
inline const TYPE& CLASS::options() const { return *options_; }
1010
PROTOBUF_DEFINE_STRING_ACCESSOR(Descriptor, name)
1011
PROTOBUF_DEFINE_STRING_ACCESSOR(Descriptor, full_name)
1012
PROTOBUF_DEFINE_ACCESSOR(Descriptor, file, const FileDescriptor*)
1013
PROTOBUF_DEFINE_ACCESSOR(Descriptor, containing_type, const Descriptor*)
1015
PROTOBUF_DEFINE_ACCESSOR(Descriptor, field_count, int)
1016
PROTOBUF_DEFINE_ACCESSOR(Descriptor, nested_type_count, int)
1017
PROTOBUF_DEFINE_ACCESSOR(Descriptor, enum_type_count, int)
1019
PROTOBUF_DEFINE_ARRAY_ACCESSOR(Descriptor, field, const FieldDescriptor*)
1020
PROTOBUF_DEFINE_ARRAY_ACCESSOR(Descriptor, nested_type, const Descriptor*)
1021
PROTOBUF_DEFINE_ARRAY_ACCESSOR(Descriptor, enum_type, const EnumDescriptor*)
1023
PROTOBUF_DEFINE_ACCESSOR(Descriptor, extension_range_count, int)
1024
PROTOBUF_DEFINE_ACCESSOR(Descriptor, extension_count, int)
1025
PROTOBUF_DEFINE_ARRAY_ACCESSOR(Descriptor, extension_range,
1026
const Descriptor::ExtensionRange*)
1027
PROTOBUF_DEFINE_ARRAY_ACCESSOR(Descriptor, extension,
1028
const FieldDescriptor*)
1029
PROTOBUF_DEFINE_OPTIONS_ACCESSOR(Descriptor, MessageOptions);
1031
PROTOBUF_DEFINE_STRING_ACCESSOR(FieldDescriptor, name)
1032
PROTOBUF_DEFINE_STRING_ACCESSOR(FieldDescriptor, full_name)
1033
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, file, const FileDescriptor*)
1034
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, number, int)
1035
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, is_extension, bool)
1036
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, type, FieldDescriptor::Type)
1037
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, label, FieldDescriptor::Label)
1038
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, containing_type, const Descriptor*)
1039
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, extension_scope, const Descriptor*)
1040
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, message_type, const Descriptor*)
1041
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, enum_type, const EnumDescriptor*)
1042
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, experimental_map_key,
1043
const FieldDescriptor*)
1044
PROTOBUF_DEFINE_OPTIONS_ACCESSOR(FieldDescriptor, FieldOptions);
1045
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, has_default_value, bool)
1046
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, default_value_int32 , int32 )
1047
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, default_value_int64 , int64 )
1048
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, default_value_uint32, uint32)
1049
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, default_value_uint64, uint64)
1050
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, default_value_float , float )
1051
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, default_value_double, double)
1052
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, default_value_bool , bool )
1053
PROTOBUF_DEFINE_ACCESSOR(FieldDescriptor, default_value_enum,
1054
const EnumValueDescriptor*)
1055
PROTOBUF_DEFINE_STRING_ACCESSOR(FieldDescriptor, default_value_string)
1057
PROTOBUF_DEFINE_STRING_ACCESSOR(EnumDescriptor, name)
1058
PROTOBUF_DEFINE_STRING_ACCESSOR(EnumDescriptor, full_name)
1059
PROTOBUF_DEFINE_ACCESSOR(EnumDescriptor, file, const FileDescriptor*)
1060
PROTOBUF_DEFINE_ACCESSOR(EnumDescriptor, containing_type, const Descriptor*)
1061
PROTOBUF_DEFINE_ACCESSOR(EnumDescriptor, value_count, int)
1062
PROTOBUF_DEFINE_ARRAY_ACCESSOR(EnumDescriptor, value,
1063
const EnumValueDescriptor*)
1064
PROTOBUF_DEFINE_OPTIONS_ACCESSOR(EnumDescriptor, EnumOptions);
1066
PROTOBUF_DEFINE_STRING_ACCESSOR(EnumValueDescriptor, name)
1067
PROTOBUF_DEFINE_STRING_ACCESSOR(EnumValueDescriptor, full_name)
1068
PROTOBUF_DEFINE_ACCESSOR(EnumValueDescriptor, number, int)
1069
PROTOBUF_DEFINE_ACCESSOR(EnumValueDescriptor, type, const EnumDescriptor*)
1070
PROTOBUF_DEFINE_OPTIONS_ACCESSOR(EnumValueDescriptor, EnumValueOptions);
1072
PROTOBUF_DEFINE_STRING_ACCESSOR(ServiceDescriptor, name)
1073
PROTOBUF_DEFINE_STRING_ACCESSOR(ServiceDescriptor, full_name)
1074
PROTOBUF_DEFINE_ACCESSOR(ServiceDescriptor, file, const FileDescriptor*)
1075
PROTOBUF_DEFINE_ACCESSOR(ServiceDescriptor, method_count, int)
1076
PROTOBUF_DEFINE_ARRAY_ACCESSOR(ServiceDescriptor, method,
1077
const MethodDescriptor*)
1078
PROTOBUF_DEFINE_OPTIONS_ACCESSOR(ServiceDescriptor, ServiceOptions);
1080
PROTOBUF_DEFINE_STRING_ACCESSOR(MethodDescriptor, name)
1081
PROTOBUF_DEFINE_STRING_ACCESSOR(MethodDescriptor, full_name)
1082
PROTOBUF_DEFINE_ACCESSOR(MethodDescriptor, service, const ServiceDescriptor*)
1083
PROTOBUF_DEFINE_ACCESSOR(MethodDescriptor, input_type, const Descriptor*)
1084
PROTOBUF_DEFINE_ACCESSOR(MethodDescriptor, output_type, const Descriptor*)
1085
PROTOBUF_DEFINE_OPTIONS_ACCESSOR(MethodDescriptor, MethodOptions);
1087
PROTOBUF_DEFINE_STRING_ACCESSOR(FileDescriptor, name)
1088
PROTOBUF_DEFINE_STRING_ACCESSOR(FileDescriptor, package)
1089
PROTOBUF_DEFINE_ACCESSOR(FileDescriptor, pool, const DescriptorPool*)
1090
PROTOBUF_DEFINE_ACCESSOR(FileDescriptor, dependency_count, int)
1091
PROTOBUF_DEFINE_ACCESSOR(FileDescriptor, message_type_count, int)
1092
PROTOBUF_DEFINE_ACCESSOR(FileDescriptor, enum_type_count, int)
1093
PROTOBUF_DEFINE_ACCESSOR(FileDescriptor, service_count, int)
1094
PROTOBUF_DEFINE_ACCESSOR(FileDescriptor, extension_count, int)
1095
PROTOBUF_DEFINE_OPTIONS_ACCESSOR(FileDescriptor, FileOptions);
1097
PROTOBUF_DEFINE_ARRAY_ACCESSOR(FileDescriptor, message_type, const Descriptor*)
1098
PROTOBUF_DEFINE_ARRAY_ACCESSOR(FileDescriptor, enum_type, const EnumDescriptor*)
1099
PROTOBUF_DEFINE_ARRAY_ACCESSOR(FileDescriptor, service,
1100
const ServiceDescriptor*)
1101
PROTOBUF_DEFINE_ARRAY_ACCESSOR(FileDescriptor, extension,
1102
const FieldDescriptor*)
1104
#undef PROTOBUF_DEFINE_ACCESSOR
1105
#undef PROTOBUF_DEFINE_STRING_ACCESSOR
1106
#undef PROTOBUF_DEFINE_ARRAY_ACCESSOR
1108
// A few accessors differ from the macros...
1110
inline bool FieldDescriptor::is_required() const {
1111
return label() == LABEL_REQUIRED;
1114
inline bool FieldDescriptor::is_optional() const {
1115
return label() == LABEL_OPTIONAL;
1118
inline bool FieldDescriptor::is_repeated() const {
1119
return label() == LABEL_REPEATED;
1122
// To save space, index() is computed by looking at the descriptor's position
1123
// in the parent's array of children.
1124
inline int FieldDescriptor::index() const {
1125
if (!is_extension_) {
1126
return this - containing_type_->fields_;
1127
} else if (extension_scope_ != NULL) {
1128
return this - extension_scope_->extensions_;
1130
return this - file_->extensions_;
1134
inline int Descriptor::index() const {
1135
if (containing_type_ == NULL) {
1136
return this - file_->message_types_;
1138
return this - containing_type_->nested_types_;
1142
inline int EnumDescriptor::index() const {
1143
if (containing_type_ == NULL) {
1144
return this - file_->enum_types_;
1146
return this - containing_type_->enum_types_;
1150
inline int EnumValueDescriptor::index() const {
1151
return this - type_->values_;
1154
inline int ServiceDescriptor::index() const {
1155
return this - file_->services_;
1158
inline int MethodDescriptor::index() const {
1159
return this - service_->methods_;
1162
inline FieldDescriptor::CppType FieldDescriptor::cpp_type() const {
1163
return kTypeToCppTypeMap[type_];
1166
inline const FileDescriptor* FileDescriptor::dependency(int index) const {
1167
return dependencies_[index];
1170
} // namespace protobuf
1172
} // namespace google
1173
#endif // GOOGLE_PROTOBUF_DESCRIPTOR_H__
added
removed
src/google/protobuf/descriptor.h
