• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 #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 FieldDescriptor::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   // Helpers for dealing with unknown fields
129 
130   // Skips a field value of the given WireType.  The input should start
131   // positioned immediately after the tag.  If unknown_fields is non-NULL,
132   // the contents of the field will be added to it.
133   static bool SkipField(io::CodedInputStream* input, uint32 tag,
134                         UnknownFieldSet* unknown_fields);
135 
136   // Reads and ignores a message from the input.  If unknown_fields is non-NULL,
137   // the contents will be added to it.
138   static bool SkipMessage(io::CodedInputStream* input,
139                           UnknownFieldSet* unknown_fields);
140 
141   // Read a packed enum field. If the is_valid function is not NULL, values for
142   // which is_valid(value) returns false are appended to unknown_fields_stream.
143   static bool ReadPackedEnumPreserveUnknowns(io::CodedInputStream* input,
144                                              uint32 field_number,
145                                              bool (*is_valid)(int),
146                                              UnknownFieldSet* unknown_fields,
147                                              RepeatedField<int>* values);
148 
149   // Write the contents of an UnknownFieldSet to the output.
150   static void SerializeUnknownFields(const UnknownFieldSet& unknown_fields,
151                                      io::CodedOutputStream* output);
152   // Same as above, except writing directly to the provided buffer.
153   // Requires that the buffer have sufficient capacity for
154   // ComputeUnknownFieldsSize(unknown_fields).
155   //
156   // Returns a pointer past the last written byte.
157   static uint8* SerializeUnknownFieldsToArray(
158       const UnknownFieldSet& unknown_fields,
159       uint8* target);
160 
161   // Same thing except for messages that have the message_set_wire_format
162   // option.
163   static void SerializeUnknownMessageSetItems(
164       const UnknownFieldSet& unknown_fields,
165       io::CodedOutputStream* output);
166   // Same as above, except writing directly to the provided buffer.
167   // Requires that the buffer have sufficient capacity for
168   // ComputeUnknownMessageSetItemsSize(unknown_fields).
169   //
170   // Returns a pointer past the last written byte.
171   static uint8* SerializeUnknownMessageSetItemsToArray(
172       const UnknownFieldSet& unknown_fields,
173       uint8* target);
174 
175   // Compute the size of the UnknownFieldSet on the wire.
176   static int ComputeUnknownFieldsSize(const UnknownFieldSet& unknown_fields);
177 
178   // Same thing except for messages that have the message_set_wire_format
179   // option.
180   static int ComputeUnknownMessageSetItemsSize(
181       const UnknownFieldSet& unknown_fields);
182 
183 
184   // Helper functions for encoding and decoding tags.  (Inlined below and in
185   // _inl.h)
186   //
187   // This is different from MakeTag(field->number(), field->type()) in the case
188   // of packed repeated fields.
189   static uint32 MakeTag(const FieldDescriptor* field);
190 
191   // Parse a single field.  The input should start out positioned immediately
192   // after the tag.
193   static bool ParseAndMergeField(
194       uint32 tag,
195       const FieldDescriptor* field,        // May be NULL for unknown
196       Message* message,
197       io::CodedInputStream* input);
198 
199   // Serialize a single field.
200   static void SerializeFieldWithCachedSizes(
201       const FieldDescriptor* field,        // Cannot be NULL
202       const Message& message,
203       io::CodedOutputStream* output);
204 
205   // Compute size of a single field.  If the field is a message type, this
206   // will call ByteSize() for the embedded message, insuring that it caches
207   // its size.
208   static int FieldByteSize(
209       const FieldDescriptor* field,        // Cannot be NULL
210       const Message& message);
211 
212   // Parse/serialize a MessageSet::Item group.  Used with messages that use
213   // opion message_set_wire_format = true.
214   static bool ParseAndMergeMessageSetItem(
215       io::CodedInputStream* input,
216       Message* message);
217   static void SerializeMessageSetItemWithCachedSizes(
218       const FieldDescriptor* field,
219       const Message& message,
220       io::CodedOutputStream* output);
221   static int MessageSetItemByteSize(
222       const FieldDescriptor* field,
223       const Message& message);
224 
225   // Computes the byte size of a field, excluding tags. For packed fields, it
226   // only includes the size of the raw data, and not the size of the total
227   // length, but for other length-delimited types, the size of the length is
228   // included.
229   static int FieldDataOnlyByteSize(
230       const FieldDescriptor* field,        // Cannot be NULL
231       const Message& message);
232 
233   enum Operation {
234     PARSE = 0,
235     SERIALIZE = 1,
236   };
237 
238   // Verifies that a string field is valid UTF8, logging an error if not.
239   // This function will not be called by newly generated protobuf code
240   // but remains present to support existing code.
241   static void VerifyUTF8String(const char* data, int size, Operation op);
242   // The NamedField variant takes a field name in order to produce an
243   // informative error message if verification fails.
244   static void VerifyUTF8StringNamedField(const char* data,
245                                          int size,
246                                          Operation op,
247                                          const char* field_name);
248 
249  private:
250   // Skip a MessageSet field.
251   static bool SkipMessageSetField(io::CodedInputStream* input,
252                                   uint32 field_number,
253                                   UnknownFieldSet* unknown_fields);
254 
255   // Parse a MessageSet field.
256   static bool ParseAndMergeMessageSetField(uint32 field_number,
257                                            const FieldDescriptor* field,
258                                            Message* message,
259                                            io::CodedInputStream* input);
260 
261   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(WireFormat);
262 };
263 
264 // Subclass of FieldSkipper which saves skipped fields to an UnknownFieldSet.
265 class LIBPROTOBUF_EXPORT UnknownFieldSetFieldSkipper : public FieldSkipper {
266  public:
UnknownFieldSetFieldSkipper(UnknownFieldSet * unknown_fields)267   UnknownFieldSetFieldSkipper(UnknownFieldSet* unknown_fields)
268       : unknown_fields_(unknown_fields) {}
~UnknownFieldSetFieldSkipper()269   virtual ~UnknownFieldSetFieldSkipper() {}
270 
271   // implements FieldSkipper -----------------------------------------
272   virtual bool SkipField(io::CodedInputStream* input, uint32 tag);
273   virtual bool SkipMessage(io::CodedInputStream* input);
274   virtual void SkipUnknownEnum(int field_number, int value);
275 
276  protected:
277   UnknownFieldSet* unknown_fields_;
278 };
279 
280 // inline methods ====================================================
281 
WireTypeForField(const FieldDescriptor * field)282 inline WireFormatLite::WireType WireFormat::WireTypeForField(
283     const FieldDescriptor* field) {
284   if (field->is_packed()) {
285     return WireFormatLite::WIRETYPE_LENGTH_DELIMITED;
286   } else {
287     return WireTypeForFieldType(field->type());
288   }
289 }
290 
WireTypeForFieldType(FieldDescriptor::Type type)291 inline WireFormatLite::WireType WireFormat::WireTypeForFieldType(
292     FieldDescriptor::Type type) {
293   // Some compilers don't like enum -> enum casts, so we implicit_cast to
294   // int first.
295   return WireFormatLite::WireTypeForFieldType(
296       static_cast<WireFormatLite::FieldType>(
297         implicit_cast<int>(type)));
298 }
299 
MakeTag(const FieldDescriptor * field)300 inline uint32 WireFormat::MakeTag(const FieldDescriptor* field) {
301   return WireFormatLite::MakeTag(field->number(), WireTypeForField(field));
302 }
303 
TagSize(int field_number,FieldDescriptor::Type type)304 inline int WireFormat::TagSize(int field_number, FieldDescriptor::Type type) {
305   // Some compilers don't like enum -> enum casts, so we implicit_cast to
306   // int first.
307   return WireFormatLite::TagSize(field_number,
308       static_cast<WireFormatLite::FieldType>(
309         implicit_cast<int>(type)));
310 }
311 
VerifyUTF8String(const char * data,int size,WireFormat::Operation op)312 inline void WireFormat::VerifyUTF8String(const char* data, int size,
313     WireFormat::Operation op) {
314 #ifdef GOOGLE_PROTOBUF_UTF8_VALIDATION_ENABLED
315   WireFormatLite::VerifyUtf8String(
316       data, size, static_cast<WireFormatLite::Operation>(op), NULL);
317 #else
318   // Avoid the compiler warning about unsued variables.
319   (void)data; (void)size; (void)op;
320 #endif
321 }
322 
VerifyUTF8StringNamedField(const char * data,int size,WireFormat::Operation op,const char * field_name)323 inline void WireFormat::VerifyUTF8StringNamedField(
324     const char* data, int size, WireFormat::Operation op,
325     const char* field_name) {
326 #ifdef GOOGLE_PROTOBUF_UTF8_VALIDATION_ENABLED
327   WireFormatLite::VerifyUtf8String(
328       data, size, static_cast<WireFormatLite::Operation>(op), field_name);
329 #else
330   // Avoid the compiler warning about unused variables.
331   (void)data; (void)size; (void)op; (void)field_name;
332 #endif
333 }
334 
335 
336 }  // namespace internal
337 }  // namespace protobuf
338 
339 }  // namespace google
340 #endif  // GOOGLE_PROTOBUF_WIRE_FORMAT_H__
341