wire_format.h revision 5821806d5e7f356e8fa4b058a389a808ea183019
1a5728872c7702ddd09537c95bc3cbd20e1f2fb09Daniel Dunbar// Protocol Buffers - Google's data interchange format 27380466f2e9a5c835344454444cd3ad89ccca6e6Chris Lattner// Copyright 2008 Google Inc. All rights reserved. 37380466f2e9a5c835344454444cd3ad89ccca6e6Chris Lattner// http://code.google.com/p/protobuf/ 47380466f2e9a5c835344454444cd3ad89ccca6e6Chris Lattner// 57380466f2e9a5c835344454444cd3ad89ccca6e6Chris Lattner// Redistribution and use in source and binary forms, with or without 67380466f2e9a5c835344454444cd3ad89ccca6e6Chris Lattner// modification, are permitted provided that the following conditions are 727a84d01614609c094029a49f7a86f0f7f8fe7f1Tanya Lattner// met: 827a84d01614609c094029a49f7a86f0f7f8fe7f1Tanya Lattner// 934b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenault// * Redistributions of source code must retain the above copyright 1027a84d01614609c094029a49f7a86f0f7f8fe7f1Tanya Lattner// notice, this list of conditions and the following disclaimer. 1127a84d01614609c094029a49f7a86f0f7f8fe7f1Tanya Lattner// * Redistributions in binary form must reproduce the above 1235d276f443462249b436951c1c663820569e1768Chris Lattner// copyright notice, this list of conditions and the following disclaimer 137380466f2e9a5c835344454444cd3ad89ccca6e6Chris Lattner// in the documentation and/or other materials provided with the 147380466f2e9a5c835344454444cd3ad89ccca6e6Chris Lattner// distribution. 15c8e89a8ce5057750c338854085dca26f8d3136acNate Begeman// * Neither the name of Google Inc. nor the names of its 167380466f2e9a5c835344454444cd3ad89ccca6e6Chris Lattner// contributors may be used to endorse or promote products derived from 177380466f2e9a5c835344454444cd3ad89ccca6e6Chris Lattner// this software without specific prior written permission. 18c8e89a8ce5057750c338854085dca26f8d3136acNate Begeman// 198e7dafec4b70303dfaff95151cd06bfc5532720cNate Begeman// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 208e7dafec4b70303dfaff95151cd06bfc5532720cNate Begeman// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 215af27e02917089dd107c58c1cfdb064544010773Nate Begeman// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22efadb7768e7c7418185f5a4010ecd8b21ca9731bJohn McCall// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23efadb7768e7c7418185f5a4010ecd8b21ca9731bJohn McCall// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24efadb7768e7c7418185f5a4010ecd8b21ca9731bJohn McCall// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25efadb7768e7c7418185f5a4010ecd8b21ca9731bJohn McCall// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26efadb7768e7c7418185f5a4010ecd8b21ca9731bJohn McCall// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27efadb7768e7c7418185f5a4010ecd8b21ca9731bJohn McCall// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 2827a84d01614609c094029a49f7a86f0f7f8fe7f1Tanya Lattner// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 297380466f2e9a5c835344454444cd3ad89ccca6e6Chris Lattner// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30863ea9aa73c0e7f19694ab7d618debbcde3e4157Chris Lattner 31863ea9aa73c0e7f19694ab7d618debbcde3e4157Chris Lattner// Author: kenton@google.com (Kenton Varda) 32863ea9aa73c0e7f19694ab7d618debbcde3e4157Chris Lattner// atenasio@google.com (Chris Atenasio) (ZigZag transform) 33863ea9aa73c0e7f19694ab7d618debbcde3e4157Chris Lattner// Based on original Protocol Buffers design by 34863ea9aa73c0e7f19694ab7d618debbcde3e4157Chris Lattner// Sanjay Ghemawat, Jeff Dean, and others. 35ecca7536488e425417dcb005c39cc15ae1947aabChris Lattner// 36ecca7536488e425417dcb005c39cc15ae1947aabChris Lattner// This header is logically internal, but is made public because it is used 37ecca7536488e425417dcb005c39cc15ae1947aabChris Lattner// from protocol-compiler-generated code, which may reside in other components. 38ecca7536488e425417dcb005c39cc15ae1947aabChris Lattner 3986c05f3f28bcf07c97dfb1881686fc43be2f47c2John McCall#ifndef GOOGLE_PROTOBUF_WIRE_FORMAT_H__ 40ecca7536488e425417dcb005c39cc15ae1947aabChris Lattner#define GOOGLE_PROTOBUF_WIRE_FORMAT_H__ 41ecca7536488e425417dcb005c39cc15ae1947aabChris Lattner 4240249e7487c3314f185c63302aaad9edde6dfd53John McCall#include <string> 4340249e7487c3314f185c63302aaad9edde6dfd53John McCall#include <google/protobuf/descriptor.pb.h> 4440249e7487c3314f185c63302aaad9edde6dfd53John McCall#include <google/protobuf/descriptor.h> 4540249e7487c3314f185c63302aaad9edde6dfd53John McCall#include <google/protobuf/message.h> 4640249e7487c3314f185c63302aaad9edde6dfd53John McCall#include <google/protobuf/wire_format_lite.h> 47020972d5d6dc1f3c49839cfbadcccf4cbefb2f4dPeter Collingbourne 48020972d5d6dc1f3c49839cfbadcccf4cbefb2f4dPeter Collingbourne// Do UTF-8 validation on string type in Debug build only 49020972d5d6dc1f3c49839cfbadcccf4cbefb2f4dPeter Collingbourne#ifndef NDEBUG 50020972d5d6dc1f3c49839cfbadcccf4cbefb2f4dPeter Collingbourne#define GOOGLE_PROTOBUF_UTF8_VALIDATION_ENABLED 5134b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenault#endif 5234b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenault 5334b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenaultnamespace google { 5434b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenaultnamespace protobuf { 5534b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenault namespace io { 5634b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenault class CodedInputStream; // coded_stream.h 5734b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenault class CodedOutputStream; // coded_stream.h 5834b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenault } 5934b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenault class UnknownFieldSet; // unknown_field_set.h 6034b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenault} 6134b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenault 6234b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenaultnamespace protobuf { 6334b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenaultnamespace internal { 6434b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenault 6534b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenault// This class is for internal use by the protocol buffer library and by 6634b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenault// protocol-complier-generated message classes. It must not be called 6734b0adb52f1528fb03313bdd5fd73632c11fc678Matt Arsenault// directly by clients. 68d29e24f24e9a130431eafefa42c36be8e7a597deRichard Smith// 699f939f75c64770c746d78579f75a49f9c657e426Aaron Ballman// 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 // Helper functions for encoding and decoding tags. (Inlined below and in 128 // _inl.h) 129 // 130 // This is different from MakeTag(field->number(), field->type()) in the case 131 // of packed repeated fields. 132 static uint32 MakeTag(const FieldDescriptor* field); 133 134 // Parse a single field. The input should start out positioned immidately 135 // after the tag. 136 static bool ParseAndMergeField( 137 uint32 tag, 138 const FieldDescriptor* field, // May be NULL for unknown 139 Message* message, 140 io::CodedInputStream* input); 141 142 // Serialize a single field. 143 static void SerializeFieldWithCachedSizes( 144 const FieldDescriptor* field, // Cannot be NULL 145 const Message& message, 146 io::CodedOutputStream* output); 147 148 // Compute size of a single field. If the field is a message type, this 149 // will call ByteSize() for the embedded message, insuring that it caches 150 // its size. 151 static int FieldByteSize( 152 const FieldDescriptor* field, // Cannot be NULL 153 const Message& message); 154 155 // Parse/serialize a MessageSet::Item group. Used with messages that use 156 // opion message_set_wire_format = true. 157 static bool ParseAndMergeMessageSetItem( 158 io::CodedInputStream* input, 159 Message* message); 160 static void SerializeMessageSetItemWithCachedSizes( 161 const FieldDescriptor* field, 162 const Message& message, 163 io::CodedOutputStream* output); 164 static int MessageSetItemByteSize( 165 const FieldDescriptor* field, 166 const Message& message); 167 168 // Computes the byte size of a field, excluding tags. For packed fields, it 169 // only includes the size of the raw data, and not the size of the total 170 // length, but for other length-delimited types, the size of the length is 171 // included. 172 static int FieldDataOnlyByteSize( 173 const FieldDescriptor* field, // Cannot be NULL 174 const Message& message); 175 176 enum Operation { 177 PARSE, 178 SERIALIZE, 179 }; 180 181 // Verifies that a string field is valid UTF8, logging an error if not. 182 static void VerifyUTF8String(const char* data, int size, Operation op); 183 184 private: 185 // Verifies that a string field is valid UTF8, logging an error if not. 186 static void VerifyUTF8StringFallback( 187 const char* data, 188 int size, 189 Operation op); 190 191 192 193 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(WireFormat); 194}; 195 196// inline methods ==================================================== 197 198inline WireFormatLite::WireType WireFormat::WireTypeForField( 199 const FieldDescriptor* field) { 200 if (field->options().packed()) { 201 return WireFormatLite::WIRETYPE_LENGTH_DELIMITED; 202 } else { 203 return WireTypeForFieldType(field->type()); 204 } 205} 206 207inline WireFormatLite::WireType WireFormat::WireTypeForFieldType( 208 FieldDescriptor::Type type) { 209 // Some compilers don't like enum -> enum casts, so we implicit_cast to 210 // int first. 211 return WireFormatLite::WireTypeForFieldType( 212 static_cast<WireFormatLite::FieldType>( 213 implicit_cast<int>(type))); 214} 215 216inline uint32 WireFormat::MakeTag(const FieldDescriptor* field) { 217 return WireFormatLite::MakeTag(field->number(), WireTypeForField(field)); 218} 219 220inline int WireFormat::TagSize(int field_number, FieldDescriptor::Type type) { 221 // Some compilers don't like enum -> enum casts, so we implicit_cast to 222 // int first. 223 return WireFormatLite::TagSize(field_number, 224 static_cast<WireFormatLite::FieldType>( 225 implicit_cast<int>(type))); 226} 227 228inline void WireFormat::VerifyUTF8String(const char* data, int size, 229 WireFormat::Operation op) { 230#ifdef GOOGLE_PROTOBUF_UTF8_VALIDATION_ENABLED 231 WireFormat::VerifyUTF8StringFallback(data, size, op); 232#endif 233} 234 235 236} // namespace internal 237} // namespace protobuf 238 239} // namespace google 240#endif // GOOGLE_PROTOBUF_WIRE_FORMAT_H__ 241