descriptor_database.h

This section contains reference documentation for working with protocol buffer classes in C++.

#include <google/protobuf/descriptor_database.h>
namespace google::protobuf

Interface for manipulating databases of descriptors.

Classes in this file

Abstract interface for a database of descriptors.
A DescriptorDatabase into which you can insert files manually.
Very similar to SimpleDescriptorDatabase, but stores all the descriptors as raw bytes and generally tries to use as little memory as possible.
A DescriptorDatabase that fetches files from a given pool.
A DescriptorDatabase that wraps two or more others.

class DescriptorDatabase

#include <google/protobuf/descriptor_database.h>
namespace google::protobuf

Abstract interface for a database of descriptors.

This is useful if you want to create a DescriptorPool which loads descriptors on-demand from some sort of large database. If the database is large, it may be inefficient to enumerate every .proto file inside it calling DescriptorPool::BuildFile() for each one. Instead, a DescriptorPool can be created which wraps a DescriptorDatabase and only builds particular descriptors when they are needed.

Known subclasses:

Members

DescriptorDatabase()
virtual
~DescriptorDatabase()
virtual bool
FindFileByName(const std::string & filename, FileDescriptorProto * output) = 0
Find a file by file name. more...
virtual bool
FindFileContainingSymbol(const std::string & symbol_name, FileDescriptorProto * output) = 0
Find the file that declares the given fully-qualified symbol name. more...
virtual bool
FindFileContainingExtension(const std::string & containing_type, int field_number, FileDescriptorProto * output) = 0
Find the file which defines an extension extending the given message type with the given field number. more...
virtual bool
FindAllExtensionNumbers(const std::string & , std::vector< int > * )
Finds the tag numbers used by all known extensions of extendee_type, and appends them to output in an undefined order. more...
virtual bool
FindAllFileNames(std::vector< std::string > * )
Finds the file names and appends them to the output in an undefined order. more...
bool
FindAllPackageNames(std::vector< std::string > * output)
Finds the package names and appends them to the output in an undefined order. more...
bool
FindAllMessageNames(std::vector< std::string > * output)
Finds the message names and appends them to the output in an undefined order. more...

virtual bool DescriptorDatabase::FindFileByName(
        const std::string & filename,
        FileDescriptorProto * output) = 0

Find a file by file name.

Fills in in *output and returns true if found. Otherwise, returns false, leaving the contents of *output undefined.


virtual bool DescriptorDatabase::FindFileContainingSymbol(
        const std::string & symbol_name,
        FileDescriptorProto * output) = 0

Find the file that declares the given fully-qualified symbol name.

If found, fills in *output and returns true, otherwise returns false and leaves *output undefined.


virtual bool DescriptorDatabase::FindFileContainingExtension(
        const std::string & containing_type,
        int field_number,
        FileDescriptorProto * output) = 0

Find the file which defines an extension extending the given message type with the given field number.

If found, fills in *output and returns true, otherwise returns false and leaves *output undefined. containing_type must be a fully-qualified type name.


virtual bool DescriptorDatabase::FindAllExtensionNumbers(
        const std::string & ,
        std::vector< int > * )

Finds the tag numbers used by all known extensions of extendee_type, and appends them to output in an undefined order.

This method is best-effort: it's not guaranteed that the database will find all extensions, and it's not guaranteed that FindFileContainingExtension will return true on all of the found numbers. Returns true if the search was successful, otherwise returns false and leaves output unchanged.

This method has a default implementation that always returns false.


virtual bool DescriptorDatabase::FindAllFileNames(
        std::vector< std::string > * )

Finds the file names and appends them to the output in an undefined order.

This method is best-effort: it's not guaranteed that the database will find all files. Returns true if the database supports searching all file names, otherwise returns false and leaves output unchanged.

This method has a default implementation that always returns false.


bool DescriptorDatabase::FindAllPackageNames(
        std::vector< std::string > * output)

Finds the package names and appends them to the output in an undefined order.

This method is best-effort: it's not guaranteed that the database will find all packages. Returns true if the database supports searching all package names, otherwise returns false and leaves output unchanged.


bool DescriptorDatabase::FindAllMessageNames(
        std::vector< std::string > * output)

Finds the message names and appends them to the output in an undefined order.

This method is best-effort: it's not guaranteed that the database will find all messages. Returns true if the database supports searching all message names, otherwise returns false and leaves output unchanged.

class SimpleDescriptorDatabase: public DescriptorDatabase

#include <google/protobuf/descriptor_database.h>
namespace google::protobuf

A DescriptorDatabase into which you can insert files manually.

FindFileContainingSymbol() is fully-implemented. When you add a file, its symbols will be indexed for this purpose. Note that the implementation may return false positives, but only if it isn't possible for the symbol to be defined in any other file. In particular, if a file defines a symbol "Foo", then searching for "Foo.[[]anything]" will match that file. This way, the database does not need to aggressively index all children of a symbol.

FindFileContainingExtension() is mostly-implemented. It works if and only if the original FieldDescriptorProto defining the extension has a fully-qualified type name in its "extendee" field (i.e. starts with a '.'). If the extendee is a relative name, SimpleDescriptorDatabase will not attempt to resolve the type, so it will not know what type the extension is extending. Therefore, calling FindFileContainingExtension() with the extension's containing type will never actually find that extension. Note that this is an unlikely problem, as all FileDescriptorProtos created by the protocol compiler (as well as ones created by calling FileDescriptor::CopyTo()) will always use fully-qualified names for all types. You only need to worry if you are constructing FileDescriptorProtos yourself, or are calling compiler::Parser directly.

Members

SimpleDescriptorDatabase()
~SimpleDescriptorDatabase()
bool
Add(const FileDescriptorProto & file)
Adds the FileDescriptorProto to the database, making a copy. more...
bool
AddAndOwn(const FileDescriptorProto * file)
Adds the FileDescriptorProto to the database and takes ownership of it.

implements DescriptorDatabase

virtual bool
FindFileByName(const std::string & filename, FileDescriptorProto * output)
Find a file by file name. more...
virtual bool
FindFileContainingSymbol(const std::string & symbol_name, FileDescriptorProto * output)
Find the file that declares the given fully-qualified symbol name. more...
virtual bool
FindFileContainingExtension(const std::string & containing_type, int field_number, FileDescriptorProto * output)
Find the file which defines an extension extending the given message type with the given field number. more...
virtual bool
FindAllExtensionNumbers(const std::string & , std::vector< int > * )
Finds the tag numbers used by all known extensions of extendee_type, and appends them to output in an undefined order. more...
virtual bool
FindAllFileNames(std::vector< std::string > * )
Finds the file names and appends them to the output in an undefined order. more...

bool SimpleDescriptorDatabase::Add(
        const FileDescriptorProto & file)

Adds the FileDescriptorProto to the database, making a copy.

The object can be deleted after Add() returns. Returns false if the file conflicted with a file already in the database, in which case an error will have been written to GOOGLE_LOG(ERROR).


virtual bool SimpleDescriptorDatabase::FindFileByName(
        const std::string & filename,
        FileDescriptorProto * output)

Find a file by file name.

Fills in in *output and returns true if found. Otherwise, returns false, leaving the contents of *output undefined.


virtual bool SimpleDescriptorDatabase::FindFileContainingSymbol(
        const std::string & symbol_name,
        FileDescriptorProto * output)

Find the file that declares the given fully-qualified symbol name.

If found, fills in *output and returns true, otherwise returns false and leaves *output undefined.


virtual bool SimpleDescriptorDatabase::FindFileContainingExtension(
        const std::string & containing_type,
        int field_number,
        FileDescriptorProto * output)

Find the file which defines an extension extending the given message type with the given field number.

If found, fills in *output and returns true, otherwise returns false and leaves *output undefined. containing_type must be a fully-qualified type name.


virtual bool SimpleDescriptorDatabase::FindAllExtensionNumbers(
        const std::string & ,
        std::vector< int > * )

Finds the tag numbers used by all known extensions of extendee_type, and appends them to output in an undefined order.

This method is best-effort: it's not guaranteed that the database will find all extensions, and it's not guaranteed that FindFileContainingExtension will return true on all of the found numbers. Returns true if the search was successful, otherwise returns false and leaves output unchanged.

This method has a default implementation that always returns false.


virtual bool SimpleDescriptorDatabase::FindAllFileNames(
        std::vector< std::string > * )

Finds the file names and appends them to the output in an undefined order.

This method is best-effort: it's not guaranteed that the database will find all files. Returns true if the database supports searching all file names, otherwise returns false and leaves output unchanged.

This method has a default implementation that always returns false.

class EncodedDescriptorDatabase: public DescriptorDatabase

#include <google/protobuf/descriptor_database.h>
namespace google::protobuf

Very similar to SimpleDescriptorDatabase, but stores all the descriptors as raw bytes and generally tries to use as little memory as possible.

The same caveats regarding FindFileContainingExtension() apply as with SimpleDescriptorDatabase.

Members

EncodedDescriptorDatabase()
~EncodedDescriptorDatabase()
bool
Add(const void * encoded_file_descriptor, int size)
Adds the FileDescriptorProto to the database. more...
bool
AddCopy(const void * encoded_file_descriptor, int size)
Like Add(), but makes a copy of the data, so that the caller does not need to keep it around.
bool
FindNameOfFileContainingSymbol(const std::string & symbol_name, std::string * output)
Like FindFileContainingSymbol but returns only the name of the file.

implements DescriptorDatabase

virtual bool
FindFileByName(const std::string & filename, FileDescriptorProto * output)
Find a file by file name. more...
virtual bool
FindFileContainingSymbol(const std::string & symbol_name, FileDescriptorProto * output)
Find the file that declares the given fully-qualified symbol name. more...
virtual bool
FindFileContainingExtension(const std::string & containing_type, int field_number, FileDescriptorProto * output)
Find the file which defines an extension extending the given message type with the given field number. more...
virtual bool
FindAllExtensionNumbers(const std::string & , std::vector< int > * )
Finds the tag numbers used by all known extensions of extendee_type, and appends them to output in an undefined order. more...
virtual bool
FindAllFileNames(std::vector< std::string > * )
Finds the file names and appends them to the output in an undefined order. more...

bool EncodedDescriptorDatabase::Add(
        const void * encoded_file_descriptor,
        int size)

Adds the FileDescriptorProto to the database.

The descriptor is provided in encoded form. The database does not make a copy of the bytes, nor does it take ownership; it's up to the caller to make sure the bytes remain valid for the life of the database. Returns false and logs an error if the bytes are not a valid FileDescriptorProto or if the file conflicted with a file already in the database.


virtual bool EncodedDescriptorDatabase::FindFileByName(
        const std::string & filename,
        FileDescriptorProto * output)

Find a file by file name.

Fills in in *output and returns true if found. Otherwise, returns false, leaving the contents of *output undefined.


virtual bool EncodedDescriptorDatabase::FindFileContainingSymbol(
        const std::string & symbol_name,
        FileDescriptorProto * output)

Find the file that declares the given fully-qualified symbol name.

If found, fills in *output and returns true, otherwise returns false and leaves *output undefined.


virtual bool EncodedDescriptorDatabase::FindFileContainingExtension(
        const std::string & containing_type,
        int field_number,
        FileDescriptorProto * output)

Find the file which defines an extension extending the given message type with the given field number.

If found, fills in *output and returns true, otherwise returns false and leaves *output undefined. containing_type must be a fully-qualified type name.


virtual bool EncodedDescriptorDatabase::FindAllExtensionNumbers(
        const std::string & ,
        std::vector< int > * )

Finds the tag numbers used by all known extensions of extendee_type, and appends them to output in an undefined order.

This method is best-effort: it's not guaranteed that the database will find all extensions, and it's not guaranteed that FindFileContainingExtension will return true on all of the found numbers. Returns true if the search was successful, otherwise returns false and leaves output unchanged.

This method has a default implementation that always returns false.


virtual bool EncodedDescriptorDatabase::FindAllFileNames(
        std::vector< std::string > * )

Finds the file names and appends them to the output in an undefined order.

This method is best-effort: it's not guaranteed that the database will find all files. Returns true if the database supports searching all file names, otherwise returns false and leaves output unchanged.

This method has a default implementation that always returns false.

class DescriptorPoolDatabase: public DescriptorDatabase

#include <google/protobuf/descriptor_database.h>
namespace google::protobuf

A DescriptorDatabase that fetches files from a given pool.

Members

explicit
DescriptorPoolDatabase(const DescriptorPool & pool)
~DescriptorPoolDatabase()

implements DescriptorDatabase

virtual bool
FindFileByName(const std::string & filename, FileDescriptorProto * output)
Find a file by file name. more...
virtual bool
FindFileContainingSymbol(const std::string & symbol_name, FileDescriptorProto * output)
Find the file that declares the given fully-qualified symbol name. more...
virtual bool
FindFileContainingExtension(const std::string & containing_type, int field_number, FileDescriptorProto * output)
Find the file which defines an extension extending the given message type with the given field number. more...
virtual bool
FindAllExtensionNumbers(const std::string & , std::vector< int > * )
Finds the tag numbers used by all known extensions of extendee_type, and appends them to output in an undefined order. more...

virtual bool DescriptorPoolDatabase::FindFileByName(
        const std::string & filename,
        FileDescriptorProto * output)

Find a file by file name.

Fills in in *output and returns true if found. Otherwise, returns false, leaving the contents of *output undefined.


virtual bool DescriptorPoolDatabase::FindFileContainingSymbol(
        const std::string & symbol_name,
        FileDescriptorProto * output)

Find the file that declares the given fully-qualified symbol name.

If found, fills in *output and returns true, otherwise returns false and leaves *output undefined.


virtual bool DescriptorPoolDatabase::FindFileContainingExtension(
        const std::string & containing_type,
        int field_number,
        FileDescriptorProto * output)

Find the file which defines an extension extending the given message type with the given field number.

If found, fills in *output and returns true, otherwise returns false and leaves *output undefined. containing_type must be a fully-qualified type name.


virtual bool DescriptorPoolDatabase::FindAllExtensionNumbers(
        const std::string & ,
        std::vector< int > * )

Finds the tag numbers used by all known extensions of extendee_type, and appends them to output in an undefined order.

This method is best-effort: it's not guaranteed that the database will find all extensions, and it's not guaranteed that FindFileContainingExtension will return true on all of the found numbers. Returns true if the search was successful, otherwise returns false and leaves output unchanged.

This method has a default implementation that always returns false.

class MergedDescriptorDatabase: public DescriptorDatabase

#include <google/protobuf/descriptor_database.h>
namespace google::protobuf

A DescriptorDatabase that wraps two or more others.

It first searches the first database and, if that fails, tries the second, and so on.

Members

MergedDescriptorDatabase(DescriptorDatabase * source1, DescriptorDatabase * source2)
Merge just two databases. The sources remain property of the caller.
explicit
MergedDescriptorDatabase(const std::vector< DescriptorDatabase * > & sources)
Merge more than two databases. more...
~MergedDescriptorDatabase()

implements DescriptorDatabase

virtual bool
FindFileByName(const std::string & filename, FileDescriptorProto * output)
Find a file by file name. more...
virtual bool
FindFileContainingSymbol(const std::string & symbol_name, FileDescriptorProto * output)
Find the file that declares the given fully-qualified symbol name. more...
virtual bool
FindFileContainingExtension(const std::string & containing_type, int field_number, FileDescriptorProto * output)
Find the file which defines an extension extending the given message type with the given field number. more...
virtual bool
FindAllExtensionNumbers(const std::string & extendee_type, std::vector< int > * output)
Merges the results of calling all databases. more...

explicit MergedDescriptorDatabase::MergedDescriptorDatabase(
        const std::vector< DescriptorDatabase * > & sources)

Merge more than two databases.

The sources remain property of the caller. The vector may be deleted after the constructor returns but the DescriptorDatabases need to stick around.


virtual bool MergedDescriptorDatabase::FindFileByName(
        const std::string & filename,
        FileDescriptorProto * output)

Find a file by file name.

Fills in in *output and returns true if found. Otherwise, returns false, leaving the contents of *output undefined.


virtual bool MergedDescriptorDatabase::FindFileContainingSymbol(
        const std::string & symbol_name,
        FileDescriptorProto * output)

Find the file that declares the given fully-qualified symbol name.

If found, fills in *output and returns true, otherwise returns false and leaves *output undefined.


virtual bool MergedDescriptorDatabase::FindFileContainingExtension(
        const std::string & containing_type,
        int field_number,
        FileDescriptorProto * output)

Find the file which defines an extension extending the given message type with the given field number.

If found, fills in *output and returns true, otherwise returns false and leaves *output undefined. containing_type must be a fully-qualified type name.


virtual bool MergedDescriptorDatabase::FindAllExtensionNumbers(
        const std::string & extendee_type,
        std::vector< int > * output)

Merges the results of calling all databases.

Returns true iff any of the databases returned true.