src/third_party/protobuf/src/google/protobuf/wire_format.h

   1 // Protocol Buffers - Google's data interchange format
   2 // Copyright 2008 Google Inc.  All rights reserved.
   3 // http://code.google.com/p/protobuf/
   4 //
   5 // Redistribution and use in source and binary forms, with or without
   6 // modification, are permitted provided that the following conditions are
   7 // met:
   8 //
   9 //     * Redistributions of source code must retain the above copyright
  10 // notice, this list of conditions and the following disclaimer.
  11 //     * Redistributions in binary form must reproduce the above
  12 // copyright notice, this list of conditions and the following disclaimer
  13 // in the documentation and/or other materials provided with the
  14 // distribution.
  15 //     * Neither the name of Google Inc. nor the names of its
  16 // contributors may be used to endorse or promote products derived from
  17 // this software without specific prior written permission.
  18 //
  19 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 // Author: kenton@google.com (Kenton Varda)
  32 //         atenasio@google.com (Chris Atenasio) (ZigZag transform)
  33 //  Based on original Protocol Buffers design by
  34 //  Sanjay Ghemawat, Jeff Dean, and others.
  35 //
  36 // This header is logically internal, but is made public because it is used
  37 // from protocol-compiler-generated code, which may reside in other components.
  38
  39 #ifndef GOOGLE_PROTOBUF_WIRE_FORMAT_H__
  40 #define GOOGLE_PROTOBUF_WIRE_FORMAT_H__
  41
  42 #include <string>
  43 #include <google/protobuf/stubs/common.h>
  44 #include <google/protobuf/descriptor.pb.h>
  45 #include <google/protobuf/descriptor.h>
  46 #include <google/protobuf/message.h>
  47 #include <google/protobuf/wire_format_lite.h>
  48
  49 // Do UTF-8 validation on string type in Debug build only
  50 #ifndef NDEBUG
  51 #define GOOGLE_PROTOBUF_UTF8_VALIDATION_ENABLED
  52 #endif
  53
  54 namespace google {
  55 namespace protobuf {
  56   namespace io {
  57     class CodedInputStream;      // coded_stream.h
  58     class CodedOutputStream;     // coded_stream.h
  59   }
  60   class UnknownFieldSet;         // unknown_field_set.h
  61 }
  62
  63 namespace protobuf {
  64 namespace internal {
  65
  66 // This class is for internal use by the protocol buffer library and by
  67 // protocol-complier-generated message classes.  It must not be called
  68 // directly by clients.
  69 //
  70 // This class contains code for implementing the binary protocol buffer
  71 // wire format via reflection.  The WireFormatLite class implements the
  72 // non-reflection based routines.
  73 //
  74 // This class is really a namespace that contains only static methods
  75 class LIBPROTOBUF_EXPORT WireFormat {
  76  public:
  77
  78   // Given a field return its WireType
  79   static inline WireFormatLite::WireType WireTypeForField(
  80       const FieldDescriptor* field);
  81
  82   // Given a FieldSescriptor::Type return its WireType
  83   static inline WireFormatLite::WireType WireTypeForFieldType(
  84       FieldDescriptor::Type type);
  85
  86   // Compute the byte size of a tag.  For groups, this includes both the start
  87   // and end tags.
  88   static inline int TagSize(int field_number, FieldDescriptor::Type type);
  89
  90   // These procedures can be used to implement the methods of Message which
  91   // handle parsing and serialization of the protocol buffer wire format
  92   // using only the Reflection interface.  When you ask the protocol
  93   // compiler to optimize for code size rather than speed, it will implement
  94   // those methods in terms of these procedures.  Of course, these are much
  95   // slower than the specialized implementations which the protocol compiler
  96   // generates when told to optimize for speed.
  97
  98   // Read a message in protocol buffer wire format.
  99   //
 100   // This procedure reads either to the end of the input stream or through
 101   // a WIRETYPE_END_GROUP tag ending the message, whichever comes first.
 102   // It returns false if the input is invalid.
 103   //
 104   // Required fields are NOT checked by this method.  You must call
 105   // IsInitialized() on the resulting message yourself.
 106   static bool ParseAndMergePartial(io::CodedInputStream* input,
 107                                    Message* message);
 108
 109   // Serialize a message in protocol buffer wire format.
 110   //
 111   // Any embedded messages within the message must have their correct sizes
 112   // cached.  However, the top-level message need not; its size is passed as
 113   // a parameter to this procedure.
 114   //
 115   // These return false iff the underlying stream returns a write error.
 116   static void SerializeWithCachedSizes(
 117       const Message& message,
 118       int size, io::CodedOutputStream* output);
 119
 120   // Implements Message::ByteSize() via reflection.  WARNING:  The result
 121   // of this method is *not* cached anywhere.  However, all embedded messages
 122   // will have their ByteSize() methods called, so their sizes will be cached.
 123   // Therefore, calling this method is sufficient to allow you to call
 124   // WireFormat::SerializeWithCachedSizes() on the same object.
 125   static int ByteSize(const Message& message);
 126
 127
 128   // Helper functions for encoding and decoding tags.  (Inlined below and in
 129   // _inl.h)
 130   //
 131   // This is different from MakeTag(field->number(), field->type()) in the case
 132   // of packed repeated fields.
 133   static uint32 MakeTag(const FieldDescriptor* field);
 134
 135   // Parse a single field.  The input should start out positioned immidately
 136   // after the tag.
 137   static bool ParseAndMergeField(
 138       uint32 tag,
 139       const FieldDescriptor* field,        // May be NULL for unknown
 140       Message* message,
 141       io::CodedInputStream* input);
 142
 143   // Serialize a single field.
 144   static void SerializeFieldWithCachedSizes(
 145       const FieldDescriptor* field,        // Cannot be NULL
 146       const Message& message,
 147       io::CodedOutputStream* output);
 148
 149   // Compute size of a single field.  If the field is a message type, this
 150   // will call ByteSize() for the embedded message, insuring that it caches
 151   // its size.
 152   static int FieldByteSize(
 153       const FieldDescriptor* field,        // Cannot be NULL
 154       const Message& message);
 155
 156   // Parse/serialize a MessageSet::Item group.  Used with messages that use
 157   // opion message_set_wire_format = true.
 158   static bool ParseAndMergeMessageSetItem(
 159       io::CodedInputStream* input,
 160       Message* message);
 161   static void SerializeMessageSetItemWithCachedSizes(
 162       const FieldDescriptor* field,
 163       const Message& message,
 164       io::CodedOutputStream* output);
 165   static int MessageSetItemByteSize(
 166       const FieldDescriptor* field,
 167       const Message& message);
 168
 169   // Computes the byte size of a field, excluding tags. For packed fields, it
 170   // only includes the size of the raw data, and not the size of the total
 171   // length, but for other length-delimited types, the size of the length is
 172   // included.
 173   static int FieldDataOnlyByteSize(
 174       const FieldDescriptor* field,        // Cannot be NULL
 175       const Message& message);
 176
 177   enum Operation {
 178     PARSE,
 179     SERIALIZE,
 180   };
 181
 182   // Verifies that a string field is valid UTF8, logging an error if not.
 183   static void VerifyUTF8String(const char* data, int size, Operation op);
 184
 185  private:
 186   // Verifies that a string field is valid UTF8, logging an error if not.
 187   static void VerifyUTF8StringFallback(
 188       const char* data,
 189       int size,
 190       Operation op);
 191
 192
 193
 194   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(WireFormat);
 195 };
 196
 197 // inline methods ====================================================
 198
 199 inline WireFormatLite::WireType WireFormat::WireTypeForField(
 200     const FieldDescriptor* field) {
 201   if (field->options().packed()) {
 202     return WireFormatLite::WIRETYPE_LENGTH_DELIMITED;
 203   } else {
 204     return WireTypeForFieldType(field->type());
 205   }
 206 }
 207
 208 inline WireFormatLite::WireType WireFormat::WireTypeForFieldType(
 209     FieldDescriptor::Type type) {
 210   // Some compilers don't like enum -> enum casts, so we implicit_cast to
 211   // int first.
 212   return WireFormatLite::WireTypeForFieldType(
 213       static_cast<WireFormatLite::FieldType>(
 214         implicit_cast<int>(type)));
 215 }
 216
 217 inline uint32 WireFormat::MakeTag(const FieldDescriptor* field) {
 218   return WireFormatLite::MakeTag(field->number(), WireTypeForField(field));
 219 }
 220
 221 inline int WireFormat::TagSize(int field_number, FieldDescriptor::Type type) {
 222   // Some compilers don't like enum -> enum casts, so we implicit_cast to
 223   // int first.
 224   return WireFormatLite::TagSize(field_number,
 225       static_cast<WireFormatLite::FieldType>(
 226         implicit_cast<int>(type)));
 227 }
 228
 229 inline void WireFormat::VerifyUTF8String(const char* data, int size,
 230     WireFormat::Operation op) {
 231 #ifdef GOOGLE_PROTOBUF_UTF8_VALIDATION_ENABLED
 232   WireFormat::VerifyUTF8StringFallback(data, size, op);
 233 #else
 234   // Avoid the compiler warning about unsued variables.
 235   (void)data; (void)size; (void)op;
 236 #endif
 237 }
 238
 239
 240 }  // namespace internal
 241 }  // namespace protobuf
 242
 243 }  // namespace google
 244 #endif  // GOOGLE_PROTOBUF_WIRE_FORMAT_H__