google/protobuf/wire_format.h

0001 // Protocol Buffers - Google's data interchange format
0002 // Copyright 2008 Google Inc.  All rights reserved.
0003 //
0004 // Use of this source code is governed by a BSD-style
0005 // license that can be found in the LICENSE file or at
0006 // https://developers.google.com/open-source/licenses/bsd
0007
0008 // Author: kenton@google.com (Kenton Varda)
0009 //         atenasio@google.com (Chris Atenasio) (ZigZag transform)
0010 //  Based on original Protocol Buffers design by
0011 //  Sanjay Ghemawat, Jeff Dean, and others.
0012 //
0013 // This header is logically internal, but is made public because it is used
0014 // from protocol-compiler-generated code, which may reside in other components.
0015
0016 #ifndef GOOGLE_PROTOBUF_WIRE_FORMAT_H__
0017 #define GOOGLE_PROTOBUF_WIRE_FORMAT_H__
0018
0019 #include <cstddef>
0020 #include <cstdint>
0021
0022 #include "absl/base/casts.h"
0023 #include "absl/log/absl_check.h"
0024 #include "absl/strings/cord.h"
0025 #include "absl/strings/string_view.h"
0026 #include "google/protobuf/descriptor.h"
0027 #include "google/protobuf/generated_message_util.h"
0028 #include "google/protobuf/io/coded_stream.h"
0029 #include "google/protobuf/message.h"
0030 #include "google/protobuf/metadata_lite.h"
0031 #include "google/protobuf/parse_context.h"
0032 #include "google/protobuf/wire_format_lite.h"
0033
0034 #ifdef SWIG
0035 #error "You cannot SWIG proto headers"
0036 #endif
0037
0038 // Must be included last.
0039 #include "google/protobuf/port_def.inc"
0040
0041 namespace google {
0042 namespace protobuf {
0043 class MapKey;           // map_field.h
0044 class UnknownFieldSet;  // unknown_field_set.h
0045 }  // namespace protobuf
0046 }  // namespace google
0047
0048 namespace google {
0049 namespace protobuf {
0050 namespace internal {
0051
0052 class TcParser;
0053
0054 // This class is for internal use by the protocol buffer library and by
0055 // protocol-compiler-generated message classes.  It must not be called
0056 // directly by clients.
0057 //
0058 // This class contains code for implementing the binary protocol buffer
0059 // wire format via reflection.  The WireFormatLite class implements the
0060 // non-reflection based routines.
0061 //
0062 // This class is really a namespace that contains only static methods
0063 class PROTOBUF_EXPORT WireFormat {
0064  public:
0065   WireFormat() = delete;
0066
0067   // Given a field return its WireType
0068   static inline WireFormatLite::WireType WireTypeForField(
0069       const FieldDescriptor* field);
0070
0071   // Given a FieldDescriptor::Type return its WireType
0072   static inline WireFormatLite::WireType WireTypeForFieldType(
0073       FieldDescriptor::Type type);
0074
0075   // Compute the byte size of a tag.  For groups, this includes both the start
0076   // and end tags.
0077   static inline size_t TagSize(int field_number, FieldDescriptor::Type type);
0078
0079   // These procedures can be used to implement the methods of Message which
0080   // handle parsing and serialization of the protocol buffer wire format
0081   // using only the Reflection interface.  When you ask the protocol
0082   // compiler to optimize for code size rather than speed, it will implement
0083   // those methods in terms of these procedures.  Of course, these are much
0084   // slower than the specialized implementations which the protocol compiler
0085   // generates when told to optimize for speed.
0086
0087   // Read a message in protocol buffer wire format.
0088   //
0089   // This procedure reads either to the end of the input stream or through
0090   // a WIRETYPE_END_GROUP tag ending the message, whichever comes first.
0091   // It returns false if the input is invalid.
0092   //
0093   // Required fields are NOT checked by this method.  You must call
0094   // IsInitialized() on the resulting message yourself.
0095   static bool ParseAndMergePartial(io::CodedInputStream* input,
0096                                    Message* message);
0097
0098   // This is meant for internal protobuf use (WireFormat is an internal class).
0099   // This is the reflective implementation of the _InternalParse functionality.
0100   static const char* _InternalParse(Message* msg, const char* ptr,
0101                                     internal::ParseContext* ctx);
0102
0103   // Serialize a message in protocol buffer wire format.
0104   //
0105   // Any embedded messages within the message must have their correct sizes
0106   // cached.  However, the top-level message need not; its size is passed as
0107   // a parameter to this procedure.
0108   //
0109   // These return false iff the underlying stream returns a write error.
0110   static void SerializeWithCachedSizes(const Message& message, int size,
0111                                        io::CodedOutputStream* output) {
0112     int expected_endpoint = output->ByteCount() + size;
0113     output->SetCur(
0114         _InternalSerialize(message, output->Cur(), output->EpsCopy()));
0115     ABSL_CHECK_EQ(output->ByteCount(), expected_endpoint)
0116         << ": Protocol message serialized to a size different from what was "
0117            "originally expected.  Perhaps it was modified by another thread "
0118            "during serialization?";
0119   }
0120   static uint8_t* _InternalSerialize(const Message& message, uint8_t* target,
0121                                      io::EpsCopyOutputStream* stream);
0122
0123   // Implements Message::ByteSize() via reflection.  WARNING:  The result
0124   // of this method is *not* cached anywhere.  However, all embedded messages
0125   // will have their ByteSize() methods called, so their sizes will be cached.
0126   // Therefore, calling this method is sufficient to allow you to call
0127   // WireFormat::SerializeWithCachedSizes() on the same object.
0128   static size_t ByteSize(const Message& message);
0129
0130   // -----------------------------------------------------------------
0131   // Helpers for dealing with unknown fields
0132
0133   // Skips a field value of the given WireType.  The input should start
0134   // positioned immediately after the tag.  If unknown_fields is non-nullptr,
0135   // the contents of the field will be added to it.
0136   static bool SkipField(io::CodedInputStream* input, uint32_t tag,
0137                         UnknownFieldSet* unknown_fields);
0138
0139   // Reads and ignores a message from the input.  If unknown_fields is
0140   // non-nullptr, the contents will be added to it.
0141   static bool SkipMessage(io::CodedInputStream* input,
0142                           UnknownFieldSet* unknown_fields);
0143
0144   // Write the contents of an UnknownFieldSet to the output.
0145   static void SerializeUnknownFields(const UnknownFieldSet& unknown_fields,
0146                                      io::CodedOutputStream* output) {
0147     output->SetCur(InternalSerializeUnknownFieldsToArray(
0148         unknown_fields, output->Cur(), output->EpsCopy()));
0149   }
0150   // Same as above, except writing directly to the provided buffer.
0151   // Requires that the buffer have sufficient capacity for
0152   // ComputeUnknownFieldsSize(unknown_fields).
0153   //
0154   // Returns a pointer past the last written byte.
0155   static uint8_t* SerializeUnknownFieldsToArray(
0156       const UnknownFieldSet& unknown_fields, uint8_t* target) {
0157     io::EpsCopyOutputStream stream(
0158         target, static_cast<int>(ComputeUnknownFieldsSize(unknown_fields)),
0159         io::CodedOutputStream::IsDefaultSerializationDeterministic());
0160     return InternalSerializeUnknownFieldsToArray(unknown_fields, target,
0161                                                  &stream);
0162   }
0163   static uint8_t* InternalSerializeUnknownFieldsToArray(
0164       const UnknownFieldSet& unknown_fields, uint8_t* target,
0165       io::EpsCopyOutputStream* stream);
0166
0167
0168   // Same thing except for messages that have the message_set_wire_format
0169   // option.
0170   // Requires that the buffer have sufficient capacity for
0171   // ComputeUnknownMessageSetItemsSize(unknown_fields).
0172   //
0173   // Returns a pointer past the last written byte.
0174   static uint8_t* InternalSerializeUnknownMessageSetItemsToArray(
0175       const UnknownFieldSet& unknown_fields, uint8_t* target,
0176       io::EpsCopyOutputStream* stream);
0177
0178   // Compute the size of the UnknownFieldSet on the wire.
0179   static size_t ComputeUnknownFieldsSize(const UnknownFieldSet& unknown_fields);
0180
0181   // Same thing except for messages that have the message_set_wire_format
0182   // option.
0183   static size_t ComputeUnknownMessageSetItemsSize(
0184       const UnknownFieldSet& unknown_fields);
0185
0186   // Helper functions for encoding and decoding tags.  (Inlined below and in
0187   // _inl.h)
0188   //
0189   // This is different from MakeTag(field->number(), field->type()) in the
0190   // case of packed repeated fields.
0191   static uint32_t MakeTag(const FieldDescriptor* field);
0192
0193   // Parse a single field.  The input should start out positioned immediately
0194   // after the tag.
0195   static bool ParseAndMergeField(
0196       uint32_t tag,
0197       const FieldDescriptor* field,  // May be nullptr for unknown
0198       Message* message, io::CodedInputStream* input);
0199
0200   // Serialize a single field.
0201   static void SerializeFieldWithCachedSizes(
0202       const FieldDescriptor* field,  // Cannot be nullptr
0203       const Message& message, io::CodedOutputStream* output) {
0204     output->SetCur(InternalSerializeField(field, message, output->Cur(),
0205                                           output->EpsCopy()));
0206   }
0207   static uint8_t* InternalSerializeField(
0208       const FieldDescriptor* field,  // Cannot be nullptr
0209       const Message& message, uint8_t* target, io::EpsCopyOutputStream* stream);
0210
0211   // Compute size of a single field.  If the field is a message type, this
0212   // will call ByteSize() for the embedded message, insuring that it caches
0213   // its size.
0214   static size_t FieldByteSize(const FieldDescriptor* field,  // Can't be nullptr
0215                               const Message& message);
0216
0217   // Parse/serialize a MessageSet::Item group.  Used with messages that use
0218   // option message_set_wire_format = true.
0219   static bool ParseAndMergeMessageSetItem(io::CodedInputStream* input,
0220                                           Message* message);
0221   static uint8_t* InternalSerializeMessageSetItem(
0222       const FieldDescriptor* field, const Message& message, uint8_t* target,
0223       io::EpsCopyOutputStream* stream);
0224   static size_t MessageSetItemByteSize(const FieldDescriptor* field,
0225                                        const Message& message);
0226
0227   // Computes the byte size of a field, excluding tags. For packed fields, it
0228   // only includes the size of the raw data, and not the size of the total
0229   // length, but for other length-prefixed types, the size of the length is
0230   // included.
0231   static size_t FieldDataOnlyByteSize(
0232       const FieldDescriptor* field,  // Cannot be nullptr
0233       const Message& message);
0234
0235   enum Operation {
0236     PARSE = 0,
0237     SERIALIZE = 1,
0238   };
0239
0240   // Verifies that a string field is valid UTF8, logging an error if not.
0241   // This function will not be called by newly generated protobuf code
0242   // but remains present to support existing code.
0243   static void VerifyUTF8String(const char* data, int size, Operation op);
0244   // The NamedField variant takes a field name in order to produce an
0245   // informative error message if verification fails.
0246   static void VerifyUTF8StringNamedField(const char* data, int size,
0247                                          Operation op,
0248                                          absl::string_view field_name);
0249
0250  private:
0251   struct MessageSetParser;
0252   friend class TcParser;
0253   // Skip a MessageSet field.
0254   static bool SkipMessageSetField(io::CodedInputStream* input,
0255                                   uint32_t field_number,
0256                                   UnknownFieldSet* unknown_fields);
0257
0258   // Parse a MessageSet field.
0259   static bool ParseAndMergeMessageSetField(uint32_t field_number,
0260                                            const FieldDescriptor* field,
0261                                            Message* message,
0262                                            io::CodedInputStream* input);
0263   // Parses the value from the wire that belongs to tag.
0264   static const char* _InternalParseAndMergeField(Message* msg, const char* ptr,
0265                                                  internal::ParseContext* ctx,
0266                                                  uint64_t tag,
0267                                                  const Reflection* reflection,
0268                                                  const FieldDescriptor* field);
0269 };
0270
0271 // Subclass of FieldSkipper which saves skipped fields to an UnknownFieldSet.
0272 class PROTOBUF_EXPORT UnknownFieldSetFieldSkipper : public FieldSkipper {
0273  public:
0274   explicit UnknownFieldSetFieldSkipper(UnknownFieldSet* unknown_fields)
0275       : unknown_fields_(unknown_fields) {}
0276   ~UnknownFieldSetFieldSkipper() override = default;
0277
0278   // implements FieldSkipper -----------------------------------------
0279   bool SkipField(io::CodedInputStream* input, uint32_t tag) override;
0280   bool SkipMessage(io::CodedInputStream* input) override;
0281   void SkipUnknownEnum(int field_number, int value) override;
0282
0283  protected:
0284   UnknownFieldSet* unknown_fields_;
0285 };
0286
0287 // inline methods ====================================================
0288
0289 inline WireFormatLite::WireType WireFormat::WireTypeForField(
0290     const FieldDescriptor* field) {
0291   if (field->is_packed()) {
0292     return WireFormatLite::WIRETYPE_LENGTH_DELIMITED;
0293   } else {
0294     return WireTypeForFieldType(field->type());
0295   }
0296 }
0297
0298 inline WireFormatLite::WireType WireFormat::WireTypeForFieldType(
0299     FieldDescriptor::Type type) {
0300   // Some compilers don't like enum -> enum casts, so we implicit_cast to
0301   // int first.
0302   return WireFormatLite::WireTypeForFieldType(
0303       static_cast<WireFormatLite::FieldType>(absl::implicit_cast<int>(type)));
0304 }
0305
0306 inline uint32_t WireFormat::MakeTag(const FieldDescriptor* field) {
0307   return WireFormatLite::MakeTag(field->number(), WireTypeForField(field));
0308 }
0309
0310 inline size_t WireFormat::TagSize(int field_number,
0311                                   FieldDescriptor::Type type) {
0312   // Some compilers don't like enum -> enum casts, so we implicit_cast to
0313   // int first.
0314   return WireFormatLite::TagSize(
0315       field_number,
0316       static_cast<WireFormatLite::FieldType>(absl::implicit_cast<int>(type)));
0317 }
0318
0319 inline void WireFormat::VerifyUTF8String(const char* data, int size,
0320                                          WireFormat::Operation op) {
0321 #ifdef GOOGLE_PROTOBUF_UTF8_VALIDATION_ENABLED
0322   WireFormatLite::VerifyUtf8String(data, size,
0323                                    static_cast<WireFormatLite::Operation>(op),
0324                                    /* field_name = */ "");
0325 #else
0326   // Avoid the compiler warning about unused variables.
0327   (void)data;
0328   (void)size;
0329   (void)op;
0330 #endif
0331 }
0332
0333 inline void WireFormat::VerifyUTF8StringNamedField(
0334     const char* data, int size, WireFormat::Operation op,
0335     const absl::string_view field_name) {
0336 #ifdef GOOGLE_PROTOBUF_UTF8_VALIDATION_ENABLED
0337   WireFormatLite::VerifyUtf8String(
0338       data, size, static_cast<WireFormatLite::Operation>(op), field_name);
0339 #else
0340   // Avoid the compiler warning about unused variables.
0341   (void)data;
0342   (void)size;
0343   (void)op;
0344   (void)field_name;
0345 #endif
0346 }
0347
0348
0349 inline uint8_t* InternalSerializeUnknownMessageSetItemsToArray(
0350     const UnknownFieldSet& unknown_fields, uint8_t* target,
0351     io::EpsCopyOutputStream* stream) {
0352   return WireFormat::InternalSerializeUnknownMessageSetItemsToArray(
0353       unknown_fields, target, stream);
0354 }
0355
0356 inline size_t ComputeUnknownMessageSetItemsSize(
0357     const UnknownFieldSet& unknown_fields) {
0358   return WireFormat::ComputeUnknownMessageSetItemsSize(unknown_fields);
0359 }
0360
0361 // Compute the size of the UnknownFieldSet on the wire.
0362 PROTOBUF_EXPORT
0363 size_t ComputeUnknownFieldsSize(const InternalMetadata& metadata, size_t size,
0364                                 CachedSize* cached_size);
0365
0366 size_t MapKeyDataOnlyByteSize(const FieldDescriptor* field,
0367                               const MapKey& value);
0368
0369 uint8_t* SerializeMapKeyWithCachedSizes(const FieldDescriptor* field,
0370                                         const MapKey& value, uint8_t* target,
0371                                         io::EpsCopyOutputStream* stream);
0372 }  // namespace internal
0373 }  // namespace protobuf
0374 }  // namespace google
0375
0376 #include "google/protobuf/port_undef.inc"
0377
0378 #endif  // GOOGLE_PROTOBUF_WIRE_FORMAT_H__