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/descriptor.pb.h> 44#include <google/protobuf/descriptor.h> 45#include <google/protobuf/message.h> 46#include <google/protobuf/wire_format_lite.h> 47 48// Do UTF-8 validation on string type in Debug build only 49#ifndef NDEBUG 50#define GOOGLE_PROTOBUF_UTF8_VALIDATION_ENABLED 51#endif 52 53namespace google { 54namespace protobuf { 55 namespace io { 56 class CodedInputStream; // coded_stream.h 57 class CodedOutputStream; // coded_stream.h 58 } 59 class UnknownFieldSet; // unknown_field_set.h 60} 61 62namespace protobuf { 63namespace internal { 64 65// This class is for internal use by the protocol buffer library and by 66// protocol-complier-generated message classes. It must not be called 67// directly by clients. 68// 69// This class contains code for implementing the binary protocol buffer 70// wire format via reflection. The WireFormatLite class implements the 71// non-reflection based routines. 72// 73// This class is really a namespace that contains only static methods 74class LIBPROTOBUF_EXPORT WireFormat { 75 public: 76 77 // Given a field return its WireType 78 static inline WireFormatLite::WireType WireTypeForField( 79 const FieldDescriptor* field); 80 81 // Given a FieldSescriptor::Type return its WireType 82 static inline WireFormatLite::WireType WireTypeForFieldType( 83 FieldDescriptor::Type type); 84 85 // Compute the byte size of a tag. For groups, this includes both the start 86 // and end tags. 87 static inline int TagSize(int field_number, FieldDescriptor::Type type); 88 89 // These procedures can be used to implement the methods of Message which 90 // handle parsing and serialization of the protocol buffer wire format 91 // using only the Reflection interface. When you ask the protocol 92 // compiler to optimize for code size rather than speed, it will implement 93 // those methods in terms of these procedures. Of course, these are much 94 // slower than the specialized implementations which the protocol compiler 95 // generates when told to optimize for speed. 96 97 // Read a message in protocol buffer wire format. 98 // 99 // This procedure reads either to the end of the input stream or through 100 // a WIRETYPE_END_GROUP tag ending the message, whichever comes first. 101 // It returns false if the input is invalid. 102 // 103 // Required fields are NOT checked by this method. You must call 104 // IsInitialized() on the resulting message yourself. 105 static bool ParseAndMergePartial(io::CodedInputStream* input, 106 Message* message); 107 108 // Serialize a message in protocol buffer wire format. 109 // 110 // Any embedded messages within the message must have their correct sizes 111 // cached. However, the top-level message need not; its size is passed as 112 // a parameter to this procedure. 113 // 114 // These return false iff the underlying stream returns a write error. 115 static void SerializeWithCachedSizes( 116 const Message& message, 117 int size, io::CodedOutputStream* output); 118 119 // Implements Message::ByteSize() via reflection. WARNING: The result 120 // of this method is *not* cached anywhere. However, all embedded messages 121 // will have their ByteSize() methods called, so their sizes will be cached. 122 // Therefore, calling this method is sufficient to allow you to call 123 // WireFormat::SerializeWithCachedSizes() on the same object. 124 static int ByteSize(const Message& message); 125 126 // ----------------------------------------------------------------- 127 // Helpers for dealing with unknown fields 128 129 // Skips a field value of the given WireType. The input should start 130 // positioned immediately after the tag. If unknown_fields is non-NULL, 131 // the contents of the field will be added to it. 132 static bool SkipField(io::CodedInputStream* input, uint32 tag, 133 UnknownFieldSet* unknown_fields); 134 135 // Reads and ignores a message from the input. If unknown_fields is non-NULL, 136 // the contents will be added to it. 137 static bool SkipMessage(io::CodedInputStream* input, 138 UnknownFieldSet* unknown_fields); 139 140 // Write the contents of an UnknownFieldSet to the output. 141 static void SerializeUnknownFields(const UnknownFieldSet& unknown_fields, 142 io::CodedOutputStream* output); 143 // Same as above, except writing directly to the provided buffer. 144 // Requires that the buffer have sufficient capacity for 145 // ComputeUnknownFieldsSize(unknown_fields). 146 // 147 // Returns a pointer past the last written byte. 148 static uint8* SerializeUnknownFieldsToArray( 149 const UnknownFieldSet& unknown_fields, 150 uint8* target); 151 152 // Same thing except for messages that have the message_set_wire_format 153 // option. 154 static void SerializeUnknownMessageSetItems( 155 const UnknownFieldSet& unknown_fields, 156 io::CodedOutputStream* output); 157 // Same as above, except writing directly to the provided buffer. 158 // Requires that the buffer have sufficient capacity for 159 // ComputeUnknownMessageSetItemsSize(unknown_fields). 160 // 161 // Returns a pointer past the last written byte. 162 static uint8* SerializeUnknownMessageSetItemsToArray( 163 const UnknownFieldSet& unknown_fields, 164 uint8* target); 165 166 // Compute the size of the UnknownFieldSet on the wire. 167 static int ComputeUnknownFieldsSize(const UnknownFieldSet& unknown_fields); 168 169 // Same thing except for messages that have the message_set_wire_format 170 // option. 171 static int ComputeUnknownMessageSetItemsSize( 172 const UnknownFieldSet& unknown_fields); 173 174 175 // Helper functions for encoding and decoding tags. (Inlined below and in 176 // _inl.h) 177 // 178 // This is different from MakeTag(field->number(), field->type()) in the case 179 // of packed repeated fields. 180 static uint32 MakeTag(const FieldDescriptor* field); 181 182 // Parse a single field. The input should start out positioned immidately 183 // after the tag. 184 static bool ParseAndMergeField( 185 uint32 tag, 186 const FieldDescriptor* field, // May be NULL for unknown 187 Message* message, 188 io::CodedInputStream* input); 189 190 // Serialize a single field. 191 static void SerializeFieldWithCachedSizes( 192 const FieldDescriptor* field, // Cannot be NULL 193 const Message& message, 194 io::CodedOutputStream* output); 195 196 // Compute size of a single field. If the field is a message type, this 197 // will call ByteSize() for the embedded message, insuring that it caches 198 // its size. 199 static int FieldByteSize( 200 const FieldDescriptor* field, // Cannot be NULL 201 const Message& message); 202 203 // Parse/serialize a MessageSet::Item group. Used with messages that use 204 // opion message_set_wire_format = true. 205 static bool ParseAndMergeMessageSetItem( 206 io::CodedInputStream* input, 207 Message* message); 208 static void SerializeMessageSetItemWithCachedSizes( 209 const FieldDescriptor* field, 210 const Message& message, 211 io::CodedOutputStream* output); 212 static int MessageSetItemByteSize( 213 const FieldDescriptor* field, 214 const Message& message); 215 216 // Computes the byte size of a field, excluding tags. For packed fields, it 217 // only includes the size of the raw data, and not the size of the total 218 // length, but for other length-delimited types, the size of the length is 219 // included. 220 static int FieldDataOnlyByteSize( 221 const FieldDescriptor* field, // Cannot be NULL 222 const Message& message); 223 224 enum Operation { 225 PARSE, 226 SERIALIZE, 227 }; 228 229 // Verifies that a string field is valid UTF8, logging an error if not. 230 static void VerifyUTF8String(const char* data, int size, Operation op); 231 232 private: 233 // Verifies that a string field is valid UTF8, logging an error if not. 234 static void VerifyUTF8StringFallback( 235 const char* data, 236 int size, 237 Operation op); 238 239 240 241 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(WireFormat); 242}; 243 244// Subclass of FieldSkipper which saves skipped fields to an UnknownFieldSet. 245class LIBPROTOBUF_EXPORT UnknownFieldSetFieldSkipper : public FieldSkipper { 246 public: 247 UnknownFieldSetFieldSkipper(UnknownFieldSet* unknown_fields) 248 : unknown_fields_(unknown_fields) {} 249 virtual ~UnknownFieldSetFieldSkipper() {} 250 251 // implements FieldSkipper ----------------------------------------- 252 virtual bool SkipField(io::CodedInputStream* input, uint32 tag); 253 virtual bool SkipMessage(io::CodedInputStream* input); 254 virtual void SkipUnknownEnum(int field_number, int value); 255 256 private: 257 UnknownFieldSet* unknown_fields_; 258}; 259 260// inline methods ==================================================== 261 262inline WireFormatLite::WireType WireFormat::WireTypeForField( 263 const FieldDescriptor* field) { 264 if (field->options().packed()) { 265 return WireFormatLite::WIRETYPE_LENGTH_DELIMITED; 266 } else { 267 return WireTypeForFieldType(field->type()); 268 } 269} 270 271inline WireFormatLite::WireType WireFormat::WireTypeForFieldType( 272 FieldDescriptor::Type type) { 273 // Some compilers don't like enum -> enum casts, so we implicit_cast to 274 // int first. 275 return WireFormatLite::WireTypeForFieldType( 276 static_cast<WireFormatLite::FieldType>( 277 implicit_cast<int>(type))); 278} 279 280inline uint32 WireFormat::MakeTag(const FieldDescriptor* field) { 281 return WireFormatLite::MakeTag(field->number(), WireTypeForField(field)); 282} 283 284inline int WireFormat::TagSize(int field_number, FieldDescriptor::Type type) { 285 // Some compilers don't like enum -> enum casts, so we implicit_cast to 286 // int first. 287 return WireFormatLite::TagSize(field_number, 288 static_cast<WireFormatLite::FieldType>( 289 implicit_cast<int>(type))); 290} 291 292inline void WireFormat::VerifyUTF8String(const char* data, int size, 293 WireFormat::Operation op) { 294#ifdef GOOGLE_PROTOBUF_UTF8_VALIDATION_ENABLED 295 WireFormat::VerifyUTF8StringFallback(data, size, op); 296#endif 297} 298 299 300} // namespace internal 301} // namespace protobuf 302 303} // namespace google 304#endif // GOOGLE_PROTOBUF_WIRE_FORMAT_H__ 305