1 // Protocol Buffers - Google's data interchange format
2 // Copyright 2008 Google Inc. All rights reserved.
3 // http://code.google.com/p/protobuf/
5 // Redistribution and use in source and binary forms, with or without
6 // modification, are permitted provided that the following conditions are
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
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.
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.
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.
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.
39 #ifndef GOOGLE_PROTOBUF_WIRE_FORMAT_H__
40 #define GOOGLE_PROTOBUF_WIRE_FORMAT_H__
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>
49 // Do UTF-8 validation on string type in Debug build only
51 #define GOOGLE_PROTOBUF_UTF8_VALIDATION_ENABLED
57 class CodedInputStream; // coded_stream.h
58 class CodedOutputStream; // coded_stream.h
60 class UnknownFieldSet; // unknown_field_set.h
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.
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.
74 // This class is really a namespace that contains only static methods
75 class LIBPROTOBUF_EXPORT WireFormat {
78 // Given a field return its WireType
79 static inline WireFormatLite::WireType WireTypeForField(
80 const FieldDescriptor* field);
82 // Given a FieldSescriptor::Type return its WireType
83 static inline WireFormatLite::WireType WireTypeForFieldType(
84 FieldDescriptor::Type type);
86 // Compute the byte size of a tag. For groups, this includes both the start
88 static inline int TagSize(int field_number, FieldDescriptor::Type type);
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.
98 // Read a message in protocol buffer wire format.
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.
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,
109 // Serialize a message in protocol buffer wire format.
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.
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);
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);
128 // Helper functions for encoding and decoding tags. (Inlined below and in
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);
135 // Parse a single field. The input should start out positioned immidately
137 static bool ParseAndMergeField(
139 const FieldDescriptor* field, // May be NULL for unknown
141 io::CodedInputStream* input);
143 // Serialize a single field.
144 static void SerializeFieldWithCachedSizes(
145 const FieldDescriptor* field, // Cannot be NULL
146 const Message& message,
147 io::CodedOutputStream* output);
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
152 static int FieldByteSize(
153 const FieldDescriptor* field, // Cannot be NULL
154 const Message& message);
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,
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);
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
173 static int FieldDataOnlyByteSize(
174 const FieldDescriptor* field, // Cannot be NULL
175 const Message& message);
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);
186 // Verifies that a string field is valid UTF8, logging an error if not.
187 static void VerifyUTF8StringFallback(
194 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(WireFormat);
197 // inline methods ====================================================
199 inline WireFormatLite::WireType WireFormat::WireTypeForField(
200 const FieldDescriptor* field) {
201 if (field->options().packed()) {
202 return WireFormatLite::WIRETYPE_LENGTH_DELIMITED;
204 return WireTypeForFieldType(field->type());
208 inline WireFormatLite::WireType WireFormat::WireTypeForFieldType(
209 FieldDescriptor::Type type) {
210 // Some compilers don't like enum -> enum casts, so we implicit_cast to
212 return WireFormatLite::WireTypeForFieldType(
213 static_cast<WireFormatLite::FieldType>(
214 implicit_cast<int>(type)));
217 inline uint32 WireFormat::MakeTag(const FieldDescriptor* field) {
218 return WireFormatLite::MakeTag(field->number(), WireTypeForField(field));
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
224 return WireFormatLite::TagSize(field_number,
225 static_cast<WireFormatLite::FieldType>(
226 implicit_cast<int>(type)));
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);
234 // Avoid the compiler warning about unsued variables.
235 (void)data; (void)size; (void)op;
240 } // namespace internal
241 } // namespace protobuf
243 } // namespace google
244 #endif // GOOGLE_PROTOBUF_WIRE_FORMAT_H__