message.h

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

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

Defines Message, the abstract interface implemented by non-lite protocol message objects.

Although it's possible to implement this interface manually, most users will use the protocol compiler to generate implementations.

Example usage:

Say you have a message defined as:

message Foo {
  optional string text = 1;
  repeated int32 numbers = 2;
}

Then, if you used the protocol compiler to generate a class from the above definition, you could use it like so:

std::string data;  // Will store a serialized version of the message.

{
  // Create a message and serialize it.
  Foo foo;
  foo.set_text("Hello World!");
  foo.add_numbers(1);
  foo.add_numbers(5);
  foo.add_numbers(42);

  foo.SerializeToString(&data);
}

{
  // Parse the serialized message and check that it contains the
  // correct data.
  Foo foo;
  foo.ParseFromString(data);

  assert(foo.text() == "Hello World!");
  assert(foo.numbers_size() == 3);
  assert(foo.numbers(0) == 1);
  assert(foo.numbers(1) == 5);
  assert(foo.numbers(2) == 42);
}

{
  // Same as the last block, but do it dynamically via the Message
  // reflection interface.
  Message* foo = new Foo;
  const Descriptor* descriptor = foo->GetDescriptor();

  // Get the descriptors for the fields we're interested in and verify
  // their types.
  const FieldDescriptor* text_field = descriptor->FindFieldByName("text");
  assert(text_field != nullptr);
  assert(text_field->type() == FieldDescriptor::TYPE_STRING);
  assert(text_field->label() == FieldDescriptor::LABEL_OPTIONAL);
  const FieldDescriptor* numbers_field = descriptor->
                                         FindFieldByName("numbers");
  assert(numbers_field != nullptr);
  assert(numbers_field->type() == FieldDescriptor::TYPE_INT32);
  assert(numbers_field->label() == FieldDescriptor::LABEL_REPEATED);

  // Parse the message.
  foo->ParseFromString(data);

  // Use the reflection interface to examine the contents.
  const Reflection* reflection = foo->GetReflection();
  assert(reflection->GetString(*foo, text_field) == "Hello World!");
  assert(reflection->FieldSize(*foo, numbers_field) == 3);
  assert(reflection->GetRepeatedInt32(*foo, numbers_field, 0) == 1);
  assert(reflection->GetRepeatedInt32(*foo, numbers_field, 1) == 5);
  assert(reflection->GetRepeatedInt32(*foo, numbers_field, 2) == 42);

  delete foo;
}

Classes in this file

A container to hold message metadata.
Abstract interface for protocol messages.
This interface contains methods that can be used to dynamically access and modify the fields of a protocol message.
Abstract interface for a factory for message objects.

File Members

These definitions are not part of any class.
template const T *
DynamicCastToGenerated(const Message * from)
Tries to downcast this message to a generated message type. more...
template T *
DynamicCastToGenerated(Message * from)
template void
LinkMessageReflection()
Call this function to ensure that this message's reflection is linked into the binary: more...
const RepeatedPtrField< std::string > &
Reflection::GetRepeatedPtrFieldInternal< std::string >(const Message & message, const FieldDescriptor * field) const
RepeatedPtrField< std::string > *
Reflection::MutableRepeatedPtrFieldInternal< std::string >(Message * message, const FieldDescriptor * field) const

template const T * protobuf::DynamicCastToGenerated(
        const Message * from)

Tries to downcast this message to a generated message type.

Returns nullptr if this class is not an instance of T. This works even if RTTI is disabled.

This also has the effect of creating a strong reference to T that will prevent the linker from stripping it out at link time. This can be important if you are using a DynamicMessageFactory that delegates to the generated factory.


template void protobuf::LinkMessageReflection()

Call this function to ensure that this message's reflection is linked into the binary:

google::protobuf::LinkMessageReflection<FooMessage>();

This will ensure that the following lookup will succeed:

DescriptorPool::generated_pool()->FindMessageTypeByName("FooMessage");

As a side-effect, it will also guarantee that anything else from the same .proto file will also be available for lookup in the generated pool.

This function does not actually register the message, so it does not need to be called before the lookup. However it does need to occur in a function that cannot be stripped from the binary (ie. it must be reachable from main).

Best practice is to call this function as close as possible to where the reflection is actually needed. This function is very cheap to call, so you should not need to worry about its runtime overhead except in the tightest of loops (on x86-64 it compiles into two "mov" instructions).

struct Metadata

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

A container to hold message metadata.

Members

const Descriptor *
descriptor
const Reflection *
reflection

class Message: public MessageLite

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

Abstract interface for protocol messages.

See also MessageLite, which contains most every-day operations. Message adds descriptors and reflection on top of that.

The methods of this class that are virtual but not pure-virtual have default implementations based on reflection. Message classes which are optimized for speed will want to override these with faster implementations, but classes optimized for code size may be happy with keeping them. See the optimize_for option in descriptor.proto.

Users must not derive from this class. Only the protocol compiler and the internal library are allowed to create subclasses.

Members

constexpr
Message()
protected virtual Metadata
GetMetadata() const = 0
Get a struct containing the metadata for the Message, which is used in turn to implement GetDescriptor() and GetReflection() above.
protected explicit
Message(Arena * arena)
protected static uint64
GetInvariantPerBuild(uint64 salt)

Basic Operations

virtual Message *
New() const = 0
Construct a new instance of the same type. more...
virtual Message *
New(Arena * arena) const
Construct a new instance on the arena. more...
virtual void
CopyFrom(const Message & from)
Make this message into a copy of the given message. more...
virtual void
MergeFrom(const Message & from)
Merge the fields from the given message into this message. more...
void
CheckInitialized() const
Verifies that IsInitialized() returns true. more...
void
FindInitializationErrors(std::vector< std::string > * errors) const
Slowly build a list of all required fields that are not set. more...
virtual std::string
InitializationErrorString() const
Like FindInitializationErrors, but joins all the strings, delimited by commas, and returns them.
virtual void
DiscardUnknownFields()
Clears all unknown fields from this message and all embedded messages. more...
virtual size_t
SpaceUsedLong() const
Computes (an estimate of) the total number of bytes currently used for storing the message in memory. more...
int
SpaceUsed() const

Debugging & Testing

std::string
DebugString() const
Generates a human readable form of this message, useful for debugging and other purposes.
std::string
ShortDebugString() const
Like DebugString(), but with less whitespace.
std::string
Utf8DebugString() const
Like DebugString(), but do not escape UTF-8 byte sequences.
void
PrintDebugString() const
Convenience function useful in GDB. Prints DebugString() to stdout.

Reflection-based methods

These methods are pure-virtual in MessageLite, but Message provides reflection-based default implementations.
virtual std::string
GetTypeName() const
Get the name of this message type, e.g. "foo.bar.BazProto".
virtual void
Clear()
Clear all fields of the message and set them to their default values. more...
virtual bool
IsInitialized() const
Returns whether all required fields have been set. more...
virtual void
CheckTypeAndMergeFrom(const MessageLite & other)
If |other| is the exact same class as this, calls MergeFrom(). more...
virtual const char *
_InternalParse(const char * ptr, internal::ParseContext * ctx)
Reflective parser.
virtual size_t
ByteSizeLong() const
Computes the serialized size of the message. more...
virtual uint8 *
_InternalSerialize(uint8 * ptr, io::EpsCopyOutputStream * stream) const
Fast path when conditions match (ie. more...

Introspection

const Descriptor *
GetDescriptor() const
Get a non-owning pointer to a Descriptor for this message's type. more...
const Reflection *
GetReflection() const
Get a non-owning pointer to the Reflection interface for this Message, which can be used to read and modify the fields of the Message dynamically (in other words, without knowing the message type at compile time). more...

virtual Message * Message::New() const = 0

Construct a new instance of the same type.

Ownership is passed to the caller. (This is also defined in MessageLite, but is defined again here for return-type covariance.)


virtual Message * Message::New(
        Arena * arena) const

Construct a new instance on the arena.

Ownership is passed to the caller if arena is a nullptr. Default implementation allows for API compatibility during the Arena transition.


virtual void Message::CopyFrom(
        const Message & from)

Make this message into a copy of the given message.

The given message must have the same descriptor, but need not necessarily be the same class. By default this is just implemented as "Clear(); MergeFrom(from);".


virtual void Message::MergeFrom(
        const Message & from)

Merge the fields from the given message into this message.

Singular fields will be overwritten, if specified in from, except for embedded messages which will be merged. Repeated fields will be concatenated. The given message must be of the same type as this message (i.e. the exact same class).


void Message::CheckInitialized() const

Verifies that IsInitialized() returns true.

GOOGLE_CHECK-fails otherwise, with a nice error message.


void Message::FindInitializationErrors(
        std::vector< std::string > * errors) const

Slowly build a list of all required fields that are not set.

This is much, much slower than IsInitialized() as it is implemented purely via reflection. Generally, you should not call this unless you have already determined that an error exists by calling IsInitialized().


virtual void Message::DiscardUnknownFields()

Clears all unknown fields from this message and all embedded messages.

Normally, if unknown tag numbers are encountered when parsing a message, the tag and value are stored in the message's UnknownFieldSet and then written back out when the message is serialized. This allows servers which simply route messages to other servers to pass through messages that have new field definitions which they don't yet know about. However, this behavior can have security implications. To avoid it, call this method after parsing.

See Reflection::GetUnknownFields() for more on unknown fields.


virtual size_t Message::SpaceUsedLong() const

Computes (an estimate of) the total number of bytes currently used for storing the message in memory.

The default implementation calls the Reflection object's SpaceUsed() method.

SpaceUsed() is noticeably slower than ByteSize(), as it is implemented using reflection (rather than the generated code implementation for ByteSize()). Like ByteSize(), its CPU time is linear in the number of fields defined for the proto.


virtual void Message::Clear()

Clear all fields of the message and set them to their default values.

Clear() avoids freeing memory, assuming that any memory allocated to hold parts of the message will be needed again to hold the next message. If you actually want to free the memory used by a Message, you must delete it.


virtual bool Message::IsInitialized() const

Returns whether all required fields have been set.

Note that required fields no longer exist starting in proto3.


virtual void Message::CheckTypeAndMergeFrom(
        const MessageLite & other)

If |other| is the exact same class as this, calls MergeFrom().

Otherwise, results are undefined (probably crash).


virtual size_t Message::ByteSizeLong() const

Computes the serialized size of the message.

This recursively calls ByteSizeLong() on all embedded messages.

ByteSizeLong() is generally linear in the number of fields defined for the proto.


virtual uint8 * Message::_InternalSerialize(
        uint8 * ptr,
        io::EpsCopyOutputStream * stream) const

Fast path when conditions match (ie.

non-deterministic) uint8* _InternalSerialize(uint8* ptr) const;


const Descriptor *
    Message::GetDescriptor() const

Get a non-owning pointer to a Descriptor for this message's type.

This describes what fields the message contains, the types of those fields, etc. This object remains property of the Message.


const Reflection *
    Message::GetReflection() const

Get a non-owning pointer to the Reflection interface for this Message, which can be used to read and modify the fields of the Message dynamically (in other words, without knowing the message type at compile time).

This object remains property of the Message.

class Reflection

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

This interface contains methods that can be used to dynamically access and modify the fields of a protocol message.

Their semantics are similar to the accessors the protocol compiler generates.

To get the Reflection for a given Message, call Message::GetReflection().

This interface is separate from Message only for efficiency reasons; the vast majority of implementations of Message will share the same implementation of Reflection (GeneratedMessageReflection, defined in generated_message.h), and all Messages of a particular class should share the same Reflection object (though you should not rely on the latter fact).

There are several ways that these methods can be used incorrectly. For example, any of the following conditions will lead to undefined results (probably assertion failures):

  • The FieldDescriptor is not a field of this message type.
  • The method called is not appropriate for the field's type. For each field type in FieldDescriptor::TYPE_*, there is only one Get*() method, one Set*() method, and one Add*() method that is valid for that type. It should be obvious which (except maybe for TYPE_BYTES, which are represented using strings in C++).
  • A Get*() or Set*() method for singular fields is called on a repeated field.
  • GetRepeated*(), SetRepeated*(), or Add*() is called on a non-repeated field.
  • The Message object passed to any method is not of the right type for this Reflection object (i.e. message.GetReflection() != reflection).

You might wonder why there is not any abstract representation for a field of arbitrary type. E.g., why isn't there just a "GetField()" method that returns "const Field&", where "Field" is some class with accessors like "GetInt32Value()". The problem is that someone would have to deal with allocating these Field objects. For generated message classes, having to allocate space for an additional object to wrap every field would at least double the message's memory footprint, probably worse. Allocating the objects on-demand, on the other hand, would be expensive and prone to memory leaks. So, instead we ended up with this flat interface.

Members

const UnknownFieldSet &
GetUnknownFields(const Message & message) const
Get the UnknownFieldSet for the message. more...
UnknownFieldSet *
MutableUnknownFields(Message * message) const
Get a mutable pointer to the UnknownFieldSet for the message. more...
size_t
SpaceUsedLong(const Message & message) const
Estimate the amount of memory used by the message object.
int
SpaceUsed(const Message & message) const
bool
HasField(const Message & message, const FieldDescriptor * field) const
Check if the given non-repeated field is set.
int
FieldSize(const Message & message, const FieldDescriptor * field) const
Get the number of elements of a repeated field.
void
ClearField(Message * message, const FieldDescriptor * field) const
Clear the value of a field, so that HasField() returns false or FieldSize() returns zero.
bool
HasOneof(const Message & message, const OneofDescriptor * oneof_descriptor) const
Check if the oneof is set. more...
void
ClearOneof(Message * message, const OneofDescriptor * oneof_descriptor) const
const FieldDescriptor *
GetOneofFieldDescriptor(const Message & message, const OneofDescriptor * oneof_descriptor) const
Returns the field descriptor if the oneof is set. nullptr otherwise.
void
RemoveLast(Message * message, const FieldDescriptor * field) const
Removes the last element of a repeated field. more...
PROTOBUF_FUTURE_MUST_USE_RESULT Message *
ReleaseLast(Message * message, const FieldDescriptor * field) const
Removes the last element of a repeated message field, and returns the pointer to the caller. more...
void
Swap(Message * message1, Message * message2) const
Swap the complete contents of two messages.
void
SwapFields(Message * message1, Message * message2, const std::vector< const FieldDescriptor * > & fields) const
Swap fields listed in fields vector of two messages.
void
SwapElements(Message * message, const FieldDescriptor * field, int index1, int index2) const
Swap two elements of a repeated field.
void
ListFields(const Message & message, std::vector< const FieldDescriptor * > * output) const
List all fields of the message which are currently set, except for unknown fields, but including extension known to the parser (i.e. more...
const RepeatedPtrField< Message > &
GetRepeatedPtrFieldInternal(const Message & message, const FieldDescriptor * field) const
RepeatedPtrField< Message > *
MutableRepeatedPtrFieldInternal(Message * message, const FieldDescriptor * field) const

Singular field getters

These get the value of a non-repeated field. They return the default value for fields that aren't set.
int32
GetInt32(const Message & message, const FieldDescriptor * field) const
int64
GetInt64(const Message & message, const FieldDescriptor * field) const
uint32
GetUInt32(const Message & message, const FieldDescriptor * field) const
uint64
GetUInt64(const Message & message, const FieldDescriptor * field) const
float
GetFloat(const Message & message, const FieldDescriptor * field) const
double
GetDouble(const Message & message, const FieldDescriptor * field) const
bool
GetBool(const Message & message, const FieldDescriptor * field) const
std::string
GetString(const Message & message, const FieldDescriptor * field) const
const EnumValueDescriptor *
GetEnum(const Message & message, const FieldDescriptor * field) const
int
GetEnumValue(const Message & message, const FieldDescriptor * field) const
GetEnumValue() returns an enum field's value as an integer rather than an EnumValueDescriptor*. more...
const Message &
GetMessage(const Message & message, const FieldDescriptor * field, MessageFactory * factory = nullptr) const
See MutableMessage() for the meaning of the "factory" parameter.
const std::string &
GetStringReference(const Message & message, const FieldDescriptor * field, std::string * scratch) const
Get a string value without copying, if possible. more...

Singular field mutators

These mutate the value of a non-repeated field.
void
SetInt32(Message * message, const FieldDescriptor * field, int32 value) const
void
SetInt64(Message * message, const FieldDescriptor * field, int64 value) const
void
SetUInt32(Message * message, const FieldDescriptor * field, uint32 value) const
void
SetUInt64(Message * message, const FieldDescriptor * field, uint64 value) const
void
SetFloat(Message * message, const FieldDescriptor * field, float value) const
void
SetDouble(Message * message, const FieldDescriptor * field, double value) const
void
SetBool(Message * message, const FieldDescriptor * field, bool value) const
void
SetString(Message * message, const FieldDescriptor * field, std::string value) const
void
SetEnum(Message * message, const FieldDescriptor * field, const EnumValueDescriptor * value) const
void
SetEnumValue(Message * message, const FieldDescriptor * field, int value) const
Set an enum field's value with an integer rather than EnumValueDescriptor. more...
Message *
MutableMessage(Message * message, const FieldDescriptor * field, MessageFactory * factory = nullptr) const
Get a mutable pointer to a field with a message type. more...
void
SetAllocatedMessage(Message * message, Message * sub_message, const FieldDescriptor * field) const
Replaces the message specified by 'field' with the already-allocated object sub_message, passing ownership to the message. more...
void
UnsafeArenaSetAllocatedMessage(Message * message, Message * sub_message, const FieldDescriptor * field) const
Similar to SetAllocatedMessage, but omits all internal safety and ownership checks. more...
PROTOBUF_FUTURE_MUST_USE_RESULT Message *
ReleaseMessage(Message * message, const FieldDescriptor * field, MessageFactory * factory = nullptr) const
Releases the message specified by 'field' and returns the pointer, ReleaseMessage() will return the message the message object if it exists. more...
Message *
UnsafeArenaReleaseMessage(Message * message, const FieldDescriptor * field, MessageFactory * factory = nullptr) const
Similar to ReleaseMessage, but omits all internal safety and ownership checks. more...

Repeated field getters

These get the value of one element of a repeated field.
int32
GetRepeatedInt32(const Message & message, const FieldDescriptor * field, int index) const
int64
GetRepeatedInt64(const Message & message, const FieldDescriptor * field, int index) const
uint32
GetRepeatedUInt32(const Message & message, const FieldDescriptor * field, int index) const
uint64
GetRepeatedUInt64(const Message & message, const FieldDescriptor * field, int index) const
float
GetRepeatedFloat(const Message & message, const FieldDescriptor * field, int index) const
double
GetRepeatedDouble(const Message & message, const FieldDescriptor * field, int index) const
bool
GetRepeatedBool(const Message & message, const FieldDescriptor * field, int index) const
std::string
GetRepeatedString(const Message & message, const FieldDescriptor * field, int index) const
const EnumValueDescriptor *
GetRepeatedEnum(const Message & message, const FieldDescriptor * field, int index) const
int
GetRepeatedEnumValue(const Message & message, const FieldDescriptor * field, int index) const
GetRepeatedEnumValue() returns an enum field's value as an integer rather than an EnumValueDescriptor*. more...
const Message &
GetRepeatedMessage(const Message & message, const FieldDescriptor * field, int index) const
const std::string &
GetRepeatedStringReference(const Message & message, const FieldDescriptor * field, int index, std::string * scratch) const

Repeated field mutators

These mutate the value of one element of a repeated field.
void
SetRepeatedInt32(Message * message, const FieldDescriptor * field, int index, int32 value) const
void
SetRepeatedInt64(Message * message, const FieldDescriptor * field, int index, int64 value) const
void
SetRepeatedUInt32(Message * message, const FieldDescriptor * field, int index, uint32 value) const
void
SetRepeatedUInt64(Message * message, const FieldDescriptor * field, int index, uint64 value) const
void
SetRepeatedFloat(Message * message, const FieldDescriptor * field, int index, float value) const
void
SetRepeatedDouble(Message * message, const FieldDescriptor * field, int index, double value) const
void
SetRepeatedBool(Message * message, const FieldDescriptor * field, int index, bool value) const
void
SetRepeatedString(Message * message, const FieldDescriptor * field, int index, std::string value) const
void
SetRepeatedEnum(Message * message, const FieldDescriptor * field, int index, const EnumValueDescriptor * value) const
void
SetRepeatedEnumValue(Message * message, const FieldDescriptor * field, int index, int value) const
Set an enum field's value with an integer rather than EnumValueDescriptor. more...
Message *
MutableRepeatedMessage(Message * message, const FieldDescriptor * field, int index) const
Get a mutable pointer to an element of a repeated field with a message type.

Repeated field adders

These add an element to a repeated field.
void
AddInt32(Message * message, const FieldDescriptor * field, int32 value) const
void
AddInt64(Message * message, const FieldDescriptor * field, int64 value) const
void
AddUInt32(Message * message, const FieldDescriptor * field, uint32 value) const
void
AddUInt64(Message * message, const FieldDescriptor * field, uint64 value) const
void
AddFloat(Message * message, const FieldDescriptor * field, float value) const
void
AddDouble(Message * message, const FieldDescriptor * field, double value) const
void
AddBool(Message * message, const FieldDescriptor * field, bool value) const
void
AddString(Message * message, const FieldDescriptor * field, std::string value) const
void
AddEnum(Message * message, const FieldDescriptor * field, const EnumValueDescriptor * value) const
void
AddEnumValue(Message * message, const FieldDescriptor * field, int value) const
Add an integer value to a repeated enum field rather than EnumValueDescriptor. more...
Message *
AddMessage(Message * message, const FieldDescriptor * field, MessageFactory * factory = nullptr) const
See MutableMessage() for comments on the "factory" parameter.
void
AddAllocatedMessage(Message * message, const FieldDescriptor * field, Message * new_entry) const
Appends an already-allocated object 'new_entry' to the repeated field specified by 'field' passing ownership to the message.
template RepeatedFieldRef< T >
GetRepeatedFieldRef(const Message & message, const FieldDescriptor * field) const
Get a RepeatedFieldRef object that can be used to read the underlying repeated field. more...
template MutableRepeatedFieldRef< T >
GetMutableRepeatedFieldRef(Message * message, const FieldDescriptor * field) const
Like GetRepeatedFieldRef() but return an object that can also be used manipulate the underlying repeated field.
template const RepeatedField< T > &
GetRepeatedField(const Message & msg, const FieldDescriptor * d) const
DEPRECATED. more...
template RepeatedField< T > *
MutableRepeatedField(Message * msg, const FieldDescriptor * d) const
DEPRECATED. more...
template const RepeatedPtrField< T > &
GetRepeatedPtrField(const Message & msg, const FieldDescriptor * d) const
DEPRECATED. more...
template RepeatedPtrField< T > *
MutableRepeatedPtrField(Message * msg, const FieldDescriptor * d) const
DEPRECATED. more...

Extensions

const FieldDescriptor *
FindKnownExtensionByName(const std::string & name) const
Try to find an extension of this message type by fully-qualified field name. more...
const FieldDescriptor *
FindKnownExtensionByNumber(int number) const
Try to find an extension of this message type by field number. more...

Feature Flags

bool
SupportsUnknownEnumValues() const
Does this message support storing arbitrary integer values in enum fields? If |true|, GetEnumValue/SetEnumValue and associated repeated-field versions take arbitrary integer values, and the legacy GetEnum() getter will dynamically create an EnumValueDescriptor for any integer value without one. more...
MessageFactory *
GetMessageFactory() const
Returns the MessageFactory associated with this message. more...

const UnknownFieldSet &
    Reflection::GetUnknownFields(
        const Message & message) const

Get the UnknownFieldSet for the message.

This contains fields which were seen when the Message was parsed but were not recognized according to the Message's definition.


UnknownFieldSet *
    Reflection::MutableUnknownFields(
        Message * message) const

Get a mutable pointer to the UnknownFieldSet for the message.

This contains fields which were seen when the Message was parsed but were not recognized according to the Message's definition.


bool Reflection::HasOneof(
        const Message & message,
        const OneofDescriptor * oneof_descriptor) const

Check if the oneof is set.

Returns true if any field in oneof is set, false otherwise.


void Reflection::RemoveLast(
        Message * message,
        const FieldDescriptor * field) const

Removes the last element of a repeated field.

We don't provide a way to remove any element other than the last because it invites inefficient use, such as O(n^2) filtering loops that should have been O(n). If you want to remove an element other than the last, the best way to do it is to re-arrange the elements (using Swap()) so that the one you want removed is at the end, then call RemoveLast().


PROTOBUF_FUTURE_MUST_USE_RESULT Message *
    Reflection::ReleaseLast(
        Message * message,
        const FieldDescriptor * field) const

Removes the last element of a repeated message field, and returns the pointer to the caller.

Caller takes ownership of the returned pointer.


void Reflection::ListFields(
        const Message & message,
        std::vector< const FieldDescriptor * > * output) const

List all fields of the message which are currently set, except for unknown fields, but including extension known to the parser (i.e.

compiled in). Singular fields will only be listed if HasField(field) would return true and repeated fields will only be listed if FieldSize(field) would return non-zero. Fields (both normal fields and extension fields) will be listed ordered by field number. Use Reflection::GetUnknownFields() or message.unknown_fields() to also get access to fields/extensions unknown to the parser.


int Reflection::GetEnumValue(
        const Message & message,
        const FieldDescriptor * field) const

GetEnumValue() returns an enum field's value as an integer rather than an EnumValueDescriptor*.

If the integer value does not correspond to a known value descriptor, a new value descriptor is created. (Such a value will only be present when the new unknown-enum-value semantics are enabled for a message.)


const std::string &
    Reflection::GetStringReference(
        const Message & message,
        const FieldDescriptor * field,
        std::string * scratch) const

Get a string value without copying, if possible.

GetString() necessarily returns a copy of the string. This can be inefficient when the std::string is already stored in a std::string object in the underlying message. GetStringReference() will return a reference to the underlying std::string in this case. Otherwise, it will copy the string into *scratch and return that.

Note: It is perfectly reasonable and useful to write code like:

str = reflection->GetStringReference(message, field, &str);

This line would ensure that only one copy of the string is made regardless of the field's underlying representation. When initializing a newly-constructed string, though, it's just as fast and more readable to use code like:

std::string str = reflection->GetString(message, field);

void Reflection::SetEnumValue(
        Message * message,
        const FieldDescriptor * field,
        int value) const

Set an enum field's value with an integer rather than EnumValueDescriptor.

For proto3 this is just setting the enum field to the value specified, for proto2 it's more complicated. If value is a known enum value the field is set as usual. If the value is unknown then it is added to the unknown field set. Note this matches the behavior of parsing unknown enum values. If multiple calls with unknown values happen than they are all added to the unknown field set in order of the calls.


Message * Reflection::MutableMessage(
        Message * message,
        const FieldDescriptor * field,
        MessageFactory * factory = nullptr) const

Get a mutable pointer to a field with a message type.

If a MessageFactory is provided, it will be used to construct instances of the sub-message; otherwise, the default factory is used. If the field is an extension that does not live in the same pool as the containing message's descriptor (e.g. it lives in an overlay pool), then a MessageFactory must be provided. If you have no idea what that meant, then you probably don't need to worry about it (don't provide a MessageFactory). WARNING: If the FieldDescriptor is for a compiled-in extension, then factory->GetPrototype(field->message_type()) MUST return an instance of the compiled-in class for this type, NOT DynamicMessage.


void Reflection::SetAllocatedMessage(
        Message * message,
        Message * sub_message,
        const FieldDescriptor * field) const

Replaces the message specified by 'field' with the already-allocated object sub_message, passing ownership to the message.

If the field contained a message, that message is deleted. If sub_message is nullptr, the field is cleared.


void Reflection::UnsafeArenaSetAllocatedMessage(
        Message * message,
        Message * sub_message,
        const FieldDescriptor * field) const

Similar to SetAllocatedMessage, but omits all internal safety and ownership checks.

This method should only be used when the objects are on the same arena or paired with a call to UnsafeArenaReleaseMessage.


PROTOBUF_FUTURE_MUST_USE_RESULT Message *
    Reflection::ReleaseMessage(
        Message * message,
        const FieldDescriptor * field,
        MessageFactory * factory = nullptr) const

Releases the message specified by 'field' and returns the pointer, ReleaseMessage() will return the message the message object if it exists.

Otherwise, it may or may not return nullptr. In any case, if the return value is non-null, the caller takes ownership of the pointer. If the field existed (HasField() is true), then the returned pointer will be the same as the pointer returned by MutableMessage(). This function has the same effect as ClearField().


Message * Reflection::UnsafeArenaReleaseMessage(
        Message * message,
        const FieldDescriptor * field,
        MessageFactory * factory = nullptr) const

Similar to ReleaseMessage, but omits all internal safety and ownership checks.

This method should only be used when the objects are on the same arena or paired with a call to UnsafeArenaSetAllocatedMessage.


int Reflection::GetRepeatedEnumValue(
        const Message & message,
        const FieldDescriptor * field,
        int index) const

GetRepeatedEnumValue() returns an enum field's value as an integer rather than an EnumValueDescriptor*.

If the integer value does not correspond to a known value descriptor, a new value descriptor is created. (Such a value will only be present when the new unknown-enum-value semantics are enabled for a message.)


void Reflection::SetRepeatedEnumValue(
        Message * message,
        const FieldDescriptor * field,
        int index,
        int value) const

Set an enum field's value with an integer rather than EnumValueDescriptor.

For proto3 this is just setting the enum field to the value specified, for proto2 it's more complicated. If value is a known enum value the field is set as usual. If the value is unknown then it is added to the unknown field set. Note this matches the behavior of parsing unknown enum values. If multiple calls with unknown values happen than they are all added to the unknown field set in order of the calls.


void Reflection::AddEnumValue(
        Message * message,
        const FieldDescriptor * field,
        int value) const

Add an integer value to a repeated enum field rather than EnumValueDescriptor.

For proto3 this is just setting the enum field to the value specified, for proto2 it's more complicated. If value is a known enum value the field is set as usual. If the value is unknown then it is added to the unknown field set. Note this matches the behavior of parsing unknown enum values. If multiple calls with unknown values happen than they are all added to the unknown field set in order of the calls.


template RepeatedFieldRef< T >
    Reflection::GetRepeatedFieldRef(
        const Message & message,
        const FieldDescriptor * field) const

Get a RepeatedFieldRef object that can be used to read the underlying repeated field.

The type parameter T must be set according to the field's cpp type. The following table shows the mapping from cpp type to acceptable T.

field->cpp_type()      T
CPPTYPE_INT32        int32
CPPTYPE_UINT32       uint32
CPPTYPE_INT64        int64
CPPTYPE_UINT64       uint64
CPPTYPE_DOUBLE       double
CPPTYPE_FLOAT        float
CPPTYPE_BOOL         bool
CPPTYPE_ENUM         generated enum type or int32
CPPTYPE_STRING       std::string
CPPTYPE_MESSAGE      generated message type or google::protobuf::Message

A RepeatedFieldRef object can be copied and the resulted object will point to the same repeated field in the same message. The object can be used as long as the message is not destroyed.

Note that to use this method users need to include the header file "reflection.h" (which defines the RepeatedFieldRef class templates).


template const RepeatedField< T > &
    Reflection::GetRepeatedField(
        const Message & msg,
        const FieldDescriptor * d) const

DEPRECATED.

Please use GetRepeatedFieldRef().

for T = Cord and all protobuf scalar types except enums.


template RepeatedField< T > *
    Reflection::MutableRepeatedField(
        Message * msg,
        const FieldDescriptor * d) const

DEPRECATED.

Please use GetMutableRepeatedFieldRef().

for T = Cord and all protobuf scalar types except enums.


template const RepeatedPtrField< T > &
    Reflection::GetRepeatedPtrField(
        const Message & msg,
        const FieldDescriptor * d) const

DEPRECATED.

Please use GetRepeatedFieldRef().

for T = std::string, google::protobuf::internal::StringPieceField

google::protobuf::Message & descendants.

template RepeatedPtrField< T > *
    Reflection::MutableRepeatedPtrField(
        Message * msg,
        const FieldDescriptor * d) const

DEPRECATED.

Please use GetMutableRepeatedFieldRef().

for T = std::string, google::protobuf::internal::StringPieceField

google::protobuf::Message & descendants.

const FieldDescriptor *
    Reflection::FindKnownExtensionByName(
        const std::string & name) const

Try to find an extension of this message type by fully-qualified field name.

Returns nullptr if no extension is known for this name or number.


const FieldDescriptor *
    Reflection::FindKnownExtensionByNumber(
        int number) const

Try to find an extension of this message type by field number.

Returns nullptr if no extension is known for this name or number.


bool Reflection::SupportsUnknownEnumValues() const

Does this message support storing arbitrary integer values in enum fields? If |true|, GetEnumValue/SetEnumValue and associated repeated-field versions take arbitrary integer values, and the legacy GetEnum() getter will dynamically create an EnumValueDescriptor for any integer value without one.

If |false|, setting an unknown enum value via the integer-based setters results in undefined behavior (in practice, GOOGLE_DCHECK-fails).

Generic code that uses reflection to handle messages with enum fields should check this flag before using the integer-based setter, and either downgrade to a compatible value or use the UnknownFieldSet if not. For example:

int new_value = GetValueFromApplicationLogic();
if (reflection->SupportsUnknownEnumValues()) {
  reflection->SetEnumValue(message, field, new_value);
} else {
  if (field_descriptor->enum_type()->
          FindValueByNumber(new_value) != nullptr) {
    reflection->SetEnumValue(message, field, new_value);
  } else if (emit_unknown_enum_values) {
    reflection->MutableUnknownFields(message)->AddVarint(
        field->number(), new_value);
  } else {
    // convert value to a compatible/default value.
    new_value = CompatibleDowngrade(new_value);
    reflection->SetEnumValue(message, field, new_value);
  }
}

MessageFactory * Reflection::GetMessageFactory() const

Returns the MessageFactory associated with this message.

This can be useful for determining if a message is a generated message or not, for example:

if (message->GetReflection()->GetMessageFactory() ==
    google::protobuf::MessageFactory::generated_factory()) {
  // This is a generated message.
}

It can also be used to create more messages of this type, though Message::New() is an easier way to accomplish this.

class MessageFactory

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

Abstract interface for a factory for message objects.

Known subclasses:

Members

MessageFactory()
virtual
~MessageFactory()
virtual const Message *
GetPrototype(const Descriptor * type) = 0
Given a Descriptor, gets or constructs the default (prototype) Message of that type. more...
static MessageFactory *
generated_factory()
Gets a MessageFactory which supports all generated, compiled-in messages. more...
static void
InternalRegisterGeneratedFile(const google::protobuf::internal::DescriptorTable * table)
For internal use only: Registers a .proto file at static initialization time, to be placed in generated_factory. more...
static void
InternalRegisterGeneratedMessage(const Descriptor * descriptor, const Message * prototype)
For internal use only: Registers a message type. more...

virtual const Message * MessageFactory::GetPrototype(
        const Descriptor * type) = 0

Given a Descriptor, gets or constructs the default (prototype) Message of that type.

You can then call that message's New() method to construct a mutable message of that type.

Calling this method twice with the same Descriptor returns the same object. The returned object remains property of the factory. Also, any objects created by calling the prototype's New() method share some data with the prototype, so these must be destroyed before the MessageFactory is destroyed.

The given descriptor must outlive the returned message, and hence must outlive the MessageFactory.

Some implementations do not support all types. GetPrototype() will return nullptr if the descriptor passed in is not supported.

This method may or may not be thread-safe depending on the implementation. Each implementation should document its own degree thread-safety.


static MessageFactory * MessageFactory::generated_factory()

Gets a MessageFactory which supports all generated, compiled-in messages.

In other words, for any compiled-in type FooMessage, the following is true:

MessageFactory::generated_factory()->GetPrototype(
  FooMessage::descriptor()) == FooMessage::default_instance()

This factory supports all types which are found in DescriptorPool::generated_pool(). If given a descriptor from any other pool, GetPrototype() will return nullptr. (You can also check if a descriptor is for a generated message by checking if descriptor->file()->pool() == DescriptorPool::generated_pool().)

This factory is 100% thread-safe; calling GetPrototype() does not modify any shared data.

This factory is a singleton. The caller must not delete the object.


static void MessageFactory::InternalRegisterGeneratedFile(
        const google::protobuf::internal::DescriptorTable * table)

For internal use only: Registers a .proto file at static initialization time, to be placed in generated_factory.

The first time GetPrototype() is called with a descriptor from this file, |register_messages| will be called, with the file name as the parameter. It must call InternalRegisterGeneratedMessage() (below) to register each message type in the file. This strange mechanism is necessary because descriptors are built lazily, so we can't register types by their descriptor until we know that the descriptor exists. |filename| must be a permanent string.


static void MessageFactory::InternalRegisterGeneratedMessage(
        const Descriptor * descriptor,
        const Message * prototype)

For internal use only: Registers a message type.

Called only by the functions which are registered with InternalRegisterGeneratedFile(), above.