1 // Protocol Buffers - Google's data interchange format
2 // Copyright 2008 Google Inc. All rights reserved.
3 // https://developers.google.com/protocol-buffers/
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
44 #include <google/protobuf/stubs/common.h>
45 #include <google/protobuf/parse_context.h>
46 #include <google/protobuf/io/coded_stream.h>
47 #include <google/protobuf/descriptor.h>
48 #include <google/protobuf/generated_message_util.h>
49 #include <google/protobuf/message.h>
50 #include <google/protobuf/metadata_lite.h>
51 #include <google/protobuf/wire_format_lite.h>
52 #include <google/protobuf/stubs/casts.h>
53
54 #ifdef SWIG
55 #error "You cannot SWIG proto headers"
56 #endif
57
58 #include <google/protobuf/port_def.inc>
59
60 namespace google {
61 namespace protobuf {
62 class MapKey; // map_field.h
63 class UnknownFieldSet; // unknown_field_set.h
64 } // namespace protobuf
65 } // namespace google
66
67 namespace google {
68 namespace protobuf {
69 namespace internal {
70
71 // This class is for internal use by the protocol buffer library and by
72 // protocol-compiler-generated message classes. It must not be called
73 // directly by clients.
74 //
75 // This class contains code for implementing the binary protocol buffer
76 // wire format via reflection. The WireFormatLite class implements the
77 // non-reflection based routines.
78 //
79 // This class is really a namespace that contains only static methods
80 class PROTOBUF_EXPORT WireFormat {
81 public:
82 // Given a field return its WireType
83 static inline WireFormatLite::WireType WireTypeForField(
84 const FieldDescriptor* field);
85
86 // Given a FieldDescriptor::Type return its WireType
87 static inline WireFormatLite::WireType WireTypeForFieldType(
88 FieldDescriptor::Type type);
89
90 // Compute the byte size of a tag. For groups, this includes both the start
91 // and end tags.
92 static inline size_t TagSize(int field_number, FieldDescriptor::Type type);
93
94 // These procedures can be used to implement the methods of Message which
95 // handle parsing and serialization of the protocol buffer wire format
96 // using only the Reflection interface. When you ask the protocol
97 // compiler to optimize for code size rather than speed, it will implement
98 // those methods in terms of these procedures. Of course, these are much
99 // slower than the specialized implementations which the protocol compiler
100 // generates when told to optimize for speed.
101
102 // Read a message in protocol buffer wire format.
103 //
104 // This procedure reads either to the end of the input stream or through
105 // a WIRETYPE_END_GROUP tag ending the message, whichever comes first.
106 // It returns false if the input is invalid.
107 //
108 // Required fields are NOT checked by this method. You must call
109 // IsInitialized() on the resulting message yourself.
110 static bool ParseAndMergePartial(io::CodedInputStream* input,
111 Message* message);
112
113 // This is meant for internal protobuf use (WireFormat is an internal class).
114 // This is the reflective implementation of the _InternalParse functionality.
115 static const char* _InternalParse(Message* msg, const char* ptr,
116 internal::ParseContext* ctx);
117
118 // Serialize a message in protocol buffer wire format.
119 //
120 // Any embedded messages within the message must have their correct sizes
121 // cached. However, the top-level message need not; its size is passed as
122 // a parameter to this procedure.
123 //
124 // These return false iff the underlying stream returns a write error.
SerializeWithCachedSizes(const Message & message,int size,io::CodedOutputStream * output)125 static void SerializeWithCachedSizes(const Message& message, int size,
126 io::CodedOutputStream* output) {
127 int expected_endpoint = output->ByteCount() + size;
128 output->SetCur(
129 _InternalSerialize(message, output->Cur(), output->EpsCopy()));
130 GOOGLE_CHECK_EQ(output->ByteCount(), expected_endpoint)
131 << ": Protocol message serialized to a size different from what was "
132 "originally expected. Perhaps it was modified by another thread "
133 "during serialization?";
134 }
135 static uint8* _InternalSerialize(const Message& message, uint8* target,
136 io::EpsCopyOutputStream* stream);
137
138 // Implements Message::ByteSize() via reflection. WARNING: The result
139 // of this method is *not* cached anywhere. However, all embedded messages
140 // will have their ByteSize() methods called, so their sizes will be cached.
141 // Therefore, calling this method is sufficient to allow you to call
142 // WireFormat::SerializeWithCachedSizes() on the same object.
143 static size_t ByteSize(const Message& message);
144
145 // -----------------------------------------------------------------
146 // Helpers for dealing with unknown fields
147
148 // Skips a field value of the given WireType. The input should start
149 // positioned immediately after the tag. If unknown_fields is non-NULL,
150 // the contents of the field will be added to it.
151 static bool SkipField(io::CodedInputStream* input, uint32 tag,
152 UnknownFieldSet* unknown_fields);
153
154 // Reads and ignores a message from the input. If unknown_fields is
155 // non-NULL, the contents will be added to it.
156 static bool SkipMessage(io::CodedInputStream* input,
157 UnknownFieldSet* unknown_fields);
158
159 // Read a packed enum field. If the is_valid function is not NULL, values
160 // for which is_valid(value) returns false are appended to
161 // unknown_fields_stream.
162 static bool ReadPackedEnumPreserveUnknowns(io::CodedInputStream* input,
163 uint32 field_number,
164 bool (*is_valid)(int),
165 UnknownFieldSet* unknown_fields,
166 RepeatedField<int>* values);
167
168 // Write the contents of an UnknownFieldSet to the output.
SerializeUnknownFields(const UnknownFieldSet & unknown_fields,io::CodedOutputStream * output)169 static void SerializeUnknownFields(const UnknownFieldSet& unknown_fields,
170 io::CodedOutputStream* output) {
171 output->SetCur(InternalSerializeUnknownFieldsToArray(
172 unknown_fields, output->Cur(), output->EpsCopy()));
173 }
174 // Same as above, except writing directly to the provided buffer.
175 // Requires that the buffer have sufficient capacity for
176 // ComputeUnknownFieldsSize(unknown_fields).
177 //
178 // Returns a pointer past the last written byte.
SerializeUnknownFieldsToArray(const UnknownFieldSet & unknown_fields,uint8 * target)179 static uint8* SerializeUnknownFieldsToArray(
180 const UnknownFieldSet& unknown_fields, uint8* target) {
181 io::EpsCopyOutputStream stream(
182 target, static_cast<int>(ComputeUnknownFieldsSize(unknown_fields)),
183 io::CodedOutputStream::IsDefaultSerializationDeterministic());
184 return InternalSerializeUnknownFieldsToArray(unknown_fields, target,
185 &stream);
186 }
187 static uint8* InternalSerializeUnknownFieldsToArray(
188 const UnknownFieldSet& unknown_fields, uint8* target,
189 io::EpsCopyOutputStream* stream);
190
191 // Same thing except for messages that have the message_set_wire_format
192 // option.
SerializeUnknownMessageSetItems(const UnknownFieldSet & unknown_fields,io::CodedOutputStream * output)193 static void SerializeUnknownMessageSetItems(
194 const UnknownFieldSet& unknown_fields, io::CodedOutputStream* output) {
195 output->SetCur(InternalSerializeUnknownMessageSetItemsToArray(
196 unknown_fields, output->Cur(), output->EpsCopy()));
197 }
198 // Same as above, except writing directly to the provided buffer.
199 // Requires that the buffer have sufficient capacity for
200 // ComputeUnknownMessageSetItemsSize(unknown_fields).
201 //
202 // Returns a pointer past the last written byte.
203 static uint8* SerializeUnknownMessageSetItemsToArray(
204 const UnknownFieldSet& unknown_fields, uint8* target);
205 static uint8* InternalSerializeUnknownMessageSetItemsToArray(
206 const UnknownFieldSet& unknown_fields, uint8* target,
207 io::EpsCopyOutputStream* stream);
208
209 // Compute the size of the UnknownFieldSet on the wire.
210 static size_t ComputeUnknownFieldsSize(const UnknownFieldSet& unknown_fields);
211
212 // Same thing except for messages that have the message_set_wire_format
213 // option.
214 static size_t ComputeUnknownMessageSetItemsSize(
215 const UnknownFieldSet& unknown_fields);
216
217 // Helper functions for encoding and decoding tags. (Inlined below and in
218 // _inl.h)
219 //
220 // This is different from MakeTag(field->number(), field->type()) in the
221 // case of packed repeated fields.
222 static uint32 MakeTag(const FieldDescriptor* field);
223
224 // Parse a single field. The input should start out positioned immediately
225 // after the tag.
226 static bool ParseAndMergeField(
227 uint32 tag,
228 const FieldDescriptor* field, // May be NULL for unknown
229 Message* message, io::CodedInputStream* input);
230
231 // Serialize a single field.
SerializeFieldWithCachedSizes(const FieldDescriptor * field,const Message & message,io::CodedOutputStream * output)232 static void SerializeFieldWithCachedSizes(
233 const FieldDescriptor* field, // Cannot be NULL
234 const Message& message, io::CodedOutputStream* output) {
235 output->SetCur(InternalSerializeField(field, message, output->Cur(),
236 output->EpsCopy()));
237 }
238 static uint8* InternalSerializeField(
239 const FieldDescriptor* field, // Cannot be NULL
240 const Message& message, uint8* target, io::EpsCopyOutputStream* stream);
241
242 // Compute size of a single field. If the field is a message type, this
243 // will call ByteSize() for the embedded message, insuring that it caches
244 // its size.
245 static size_t FieldByteSize(const FieldDescriptor* field, // Cannot be NULL
246 const Message& message);
247
248 // Parse/serialize a MessageSet::Item group. Used with messages that use
249 // option message_set_wire_format = true.
250 static bool ParseAndMergeMessageSetItem(io::CodedInputStream* input,
251 Message* message);
SerializeMessageSetItemWithCachedSizes(const FieldDescriptor * field,const Message & message,io::CodedOutputStream * output)252 static void SerializeMessageSetItemWithCachedSizes(
253 const FieldDescriptor* field, const Message& message,
254 io::CodedOutputStream* output) {
255 output->SetCur(InternalSerializeMessageSetItem(
256 field, message, output->Cur(), output->EpsCopy()));
257 }
258 static uint8* InternalSerializeMessageSetItem(
259 const FieldDescriptor* field, const Message& message, uint8* target,
260 io::EpsCopyOutputStream* stream);
261 static size_t MessageSetItemByteSize(const FieldDescriptor* field,
262 const Message& message);
263
264 // Computes the byte size of a field, excluding tags. For packed fields, it
265 // only includes the size of the raw data, and not the size of the total
266 // length, but for other length-delimited types, the size of the length is
267 // included.
268 static size_t FieldDataOnlyByteSize(
269 const FieldDescriptor* field, // Cannot be NULL
270 const Message& message);
271
272 enum Operation {
273 PARSE = 0,
274 SERIALIZE = 1,
275 };
276
277 // Verifies that a string field is valid UTF8, logging an error if not.
278 // This function will not be called by newly generated protobuf code
279 // but remains present to support existing code.
280 static void VerifyUTF8String(const char* data, int size, Operation op);
281 // The NamedField variant takes a field name in order to produce an
282 // informative error message if verification fails.
283 static void VerifyUTF8StringNamedField(const char* data, int size,
284 Operation op, const char* field_name);
285
286 private:
287 struct MessageSetParser;
288 // Skip a MessageSet field.
289 static bool SkipMessageSetField(io::CodedInputStream* input,
290 uint32 field_number,
291 UnknownFieldSet* unknown_fields);
292
293 // Parse a MessageSet field.
294 static bool ParseAndMergeMessageSetField(uint32 field_number,
295 const FieldDescriptor* field,
296 Message* message,
297 io::CodedInputStream* input);
298 // Parses the value from the wire that belongs to tag.
299 static const char* _InternalParseAndMergeField(Message* msg, const char* ptr,
300 internal::ParseContext* ctx,
301 uint64 tag,
302 const Reflection* reflection,
303 const FieldDescriptor* field);
304
305 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(WireFormat);
306 };
307
308 // Subclass of FieldSkipper which saves skipped fields to an UnknownFieldSet.
309 class PROTOBUF_EXPORT UnknownFieldSetFieldSkipper : public FieldSkipper {
310 public:
UnknownFieldSetFieldSkipper(UnknownFieldSet * unknown_fields)311 UnknownFieldSetFieldSkipper(UnknownFieldSet* unknown_fields)
312 : unknown_fields_(unknown_fields) {}
~UnknownFieldSetFieldSkipper()313 ~UnknownFieldSetFieldSkipper() override {}
314
315 // implements FieldSkipper -----------------------------------------
316 bool SkipField(io::CodedInputStream* input, uint32 tag) override;
317 bool SkipMessage(io::CodedInputStream* input) override;
318 void SkipUnknownEnum(int field_number, int value) override;
319
320 protected:
321 UnknownFieldSet* unknown_fields_;
322 };
323
324 // inline methods ====================================================
325
WireTypeForField(const FieldDescriptor * field)326 inline WireFormatLite::WireType WireFormat::WireTypeForField(
327 const FieldDescriptor* field) {
328 if (field->is_packed()) {
329 return WireFormatLite::WIRETYPE_LENGTH_DELIMITED;
330 } else {
331 return WireTypeForFieldType(field->type());
332 }
333 }
334
WireTypeForFieldType(FieldDescriptor::Type type)335 inline WireFormatLite::WireType WireFormat::WireTypeForFieldType(
336 FieldDescriptor::Type type) {
337 // Some compilers don't like enum -> enum casts, so we implicit_cast to
338 // int first.
339 return WireFormatLite::WireTypeForFieldType(
340 static_cast<WireFormatLite::FieldType>(implicit_cast<int>(type)));
341 }
342
MakeTag(const FieldDescriptor * field)343 inline uint32 WireFormat::MakeTag(const FieldDescriptor* field) {
344 return WireFormatLite::MakeTag(field->number(), WireTypeForField(field));
345 }
346
TagSize(int field_number,FieldDescriptor::Type type)347 inline size_t WireFormat::TagSize(int field_number,
348 FieldDescriptor::Type type) {
349 // Some compilers don't like enum -> enum casts, so we implicit_cast to
350 // int first.
351 return WireFormatLite::TagSize(
352 field_number,
353 static_cast<WireFormatLite::FieldType>(implicit_cast<int>(type)));
354 }
355
VerifyUTF8String(const char * data,int size,WireFormat::Operation op)356 inline void WireFormat::VerifyUTF8String(const char* data, int size,
357 WireFormat::Operation op) {
358 #ifdef GOOGLE_PROTOBUF_UTF8_VALIDATION_ENABLED
359 WireFormatLite::VerifyUtf8String(
360 data, size, static_cast<WireFormatLite::Operation>(op), NULL);
361 #else
362 // Avoid the compiler warning about unused variables.
363 (void)data;
364 (void)size;
365 (void)op;
366 #endif
367 }
368
VerifyUTF8StringNamedField(const char * data,int size,WireFormat::Operation op,const char * field_name)369 inline void WireFormat::VerifyUTF8StringNamedField(const char* data, int size,
370 WireFormat::Operation op,
371 const char* field_name) {
372 #ifdef GOOGLE_PROTOBUF_UTF8_VALIDATION_ENABLED
373 WireFormatLite::VerifyUtf8String(
374 data, size, static_cast<WireFormatLite::Operation>(op), field_name);
375 #else
376 // Avoid the compiler warning about unused variables.
377 (void)data;
378 (void)size;
379 (void)op;
380 (void)field_name;
381 #endif
382 }
383
384
InternalSerializeUnknownMessageSetItemsToArray(const UnknownFieldSet & unknown_fields,uint8 * target,io::EpsCopyOutputStream * stream)385 inline uint8* InternalSerializeUnknownMessageSetItemsToArray(
386 const UnknownFieldSet& unknown_fields, uint8* target,
387 io::EpsCopyOutputStream* stream) {
388 return WireFormat::InternalSerializeUnknownMessageSetItemsToArray(
389 unknown_fields, target, stream);
390 }
391
ComputeUnknownMessageSetItemsSize(const UnknownFieldSet & unknown_fields)392 inline size_t ComputeUnknownMessageSetItemsSize(
393 const UnknownFieldSet& unknown_fields) {
394 return WireFormat::ComputeUnknownMessageSetItemsSize(unknown_fields);
395 }
396
397 // Compute the size of the UnknownFieldSet on the wire.
398 PROTOBUF_EXPORT
399 size_t ComputeUnknownFieldsSize(const InternalMetadata& metadata, size_t size,
400 CachedSize* cached_size);
401
402 size_t MapKeyDataOnlyByteSize(const FieldDescriptor* field,
403 const MapKey& value);
404
405 uint8* SerializeMapKeyWithCachedSizes(const FieldDescriptor* field,
406 const MapKey& value, uint8* target,
407 io::EpsCopyOutputStream* stream);
408 } // namespace internal
409 } // namespace protobuf
410 } // namespace google
411
412 #include <google/protobuf/port_undef.inc>
413
414 #endif // GOOGLE_PROTOBUF_WIRE_FORMAT_H__
415