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 // Utility functions to convert between protobuf binary format and proto3 JSON
32 // format.
33 #ifndef GOOGLE_PROTOBUF_UTIL_JSON_UTIL_H__
34 #define GOOGLE_PROTOBUF_UTIL_JSON_UTIL_H__
35
36 #include <google/protobuf/message.h>
37 #include <google/protobuf/util/type_resolver.h>
38 #include <google/protobuf/stubs/bytestream.h>
39
40 namespace google {
41 namespace protobuf {
42 namespace io {
43 class ZeroCopyInputStream;
44 class ZeroCopyOutputStream;
45 } // namespace io
46 namespace util {
47
48 struct JsonParseOptions {
49 // Whether to ignore unknown JSON fields during parsing
50 bool ignore_unknown_fields;
51
JsonParseOptionsJsonParseOptions52 JsonParseOptions() : ignore_unknown_fields(false) {}
53 };
54
55 struct JsonPrintOptions {
56 // Whether to add spaces, line breaks and indentation to make the JSON output
57 // easy to read.
58 bool add_whitespace;
59 // Whether to always print primitive fields. By default primitive fields with
60 // default values will be omitted in JSON joutput. For example, an int32 field
61 // set to 0 will be omitted. Set this flag to true will override the default
62 // behavior and print primitive fields regardless of their values.
63 bool always_print_primitive_fields;
64 // Whether to always print enums as ints. By default they are rendered as
65 // strings.
66 bool always_print_enums_as_ints;
67 // Whether to preserve proto field names
68 bool preserve_proto_field_names;
69
JsonPrintOptionsJsonPrintOptions70 JsonPrintOptions()
71 : add_whitespace(false),
72 always_print_primitive_fields(false),
73 always_print_enums_as_ints(false),
74 preserve_proto_field_names(false) {}
75 };
76
77 // DEPRECATED. Use JsonPrintOptions instead.
78 typedef JsonPrintOptions JsonOptions;
79
80 // Converts from protobuf message to JSON. This is a simple wrapper of
81 // BinaryToJsonString(). It will use the DescriptorPool of the passed-in
82 // message to resolve Any types.
83 LIBPROTOBUF_EXPORT util::Status MessageToJsonString(const Message& message,
84 string* output,
85 const JsonOptions& options);
86
MessageToJsonString(const Message & message,string * output)87 inline util::Status MessageToJsonString(const Message& message,
88 string* output) {
89 return MessageToJsonString(message, output, JsonOptions());
90 }
91
92 // Converts from JSON to protobuf message. This is a simple wrapper of
93 // JsonStringToBinary(). It will use the DescriptorPool of the passed-in
94 // message to resolve Any types.
95 LIBPROTOBUF_EXPORT util::Status JsonStringToMessage(const string& input,
96 Message* message,
97 const JsonParseOptions& options);
98
JsonStringToMessage(const string & input,Message * message)99 inline util::Status JsonStringToMessage(const string& input,
100 Message* message) {
101 return JsonStringToMessage(input, message, JsonParseOptions());
102 }
103
104 // Converts protobuf binary data to JSON.
105 // The conversion will fail if:
106 // 1. TypeResolver fails to resolve a type.
107 // 2. input is not valid protobuf wire format, or conflicts with the type
108 // information returned by TypeResolver.
109 // Note that unknown fields will be discarded silently.
110 LIBPROTOBUF_EXPORT util::Status BinaryToJsonStream(
111 TypeResolver* resolver,
112 const string& type_url,
113 io::ZeroCopyInputStream* binary_input,
114 io::ZeroCopyOutputStream* json_output,
115 const JsonPrintOptions& options);
116
BinaryToJsonStream(TypeResolver * resolver,const string & type_url,io::ZeroCopyInputStream * binary_input,io::ZeroCopyOutputStream * json_output)117 inline util::Status BinaryToJsonStream(
118 TypeResolver* resolver, const string& type_url,
119 io::ZeroCopyInputStream* binary_input,
120 io::ZeroCopyOutputStream* json_output) {
121 return BinaryToJsonStream(resolver, type_url, binary_input, json_output,
122 JsonPrintOptions());
123 }
124
125 LIBPROTOBUF_EXPORT util::Status BinaryToJsonString(
126 TypeResolver* resolver,
127 const string& type_url,
128 const string& binary_input,
129 string* json_output,
130 const JsonPrintOptions& options);
131
BinaryToJsonString(TypeResolver * resolver,const string & type_url,const string & binary_input,string * json_output)132 inline util::Status BinaryToJsonString(TypeResolver* resolver,
133 const string& type_url,
134 const string& binary_input,
135 string* json_output) {
136 return BinaryToJsonString(resolver, type_url, binary_input, json_output,
137 JsonPrintOptions());
138 }
139
140 // Converts JSON data to protobuf binary format.
141 // The conversion will fail if:
142 // 1. TypeResolver fails to resolve a type.
143 // 2. input is not valid JSON format, or conflicts with the type
144 // information returned by TypeResolver.
145 LIBPROTOBUF_EXPORT util::Status JsonToBinaryStream(
146 TypeResolver* resolver,
147 const string& type_url,
148 io::ZeroCopyInputStream* json_input,
149 io::ZeroCopyOutputStream* binary_output,
150 const JsonParseOptions& options);
151
JsonToBinaryStream(TypeResolver * resolver,const string & type_url,io::ZeroCopyInputStream * json_input,io::ZeroCopyOutputStream * binary_output)152 inline util::Status JsonToBinaryStream(
153 TypeResolver* resolver,
154 const string& type_url,
155 io::ZeroCopyInputStream* json_input,
156 io::ZeroCopyOutputStream* binary_output) {
157 return JsonToBinaryStream(resolver, type_url, json_input, binary_output,
158 JsonParseOptions());
159 }
160
161 LIBPROTOBUF_EXPORT util::Status JsonToBinaryString(
162 TypeResolver* resolver,
163 const string& type_url,
164 const string& json_input,
165 string* binary_output,
166 const JsonParseOptions& options);
167
JsonToBinaryString(TypeResolver * resolver,const string & type_url,const string & json_input,string * binary_output)168 inline util::Status JsonToBinaryString(
169 TypeResolver* resolver,
170 const string& type_url,
171 const string& json_input,
172 string* binary_output) {
173 return JsonToBinaryString(resolver, type_url, json_input, binary_output,
174 JsonParseOptions());
175 }
176
177 namespace internal {
178 // Internal helper class. Put in the header so we can write unit-tests for it.
179 class LIBPROTOBUF_EXPORT ZeroCopyStreamByteSink : public strings::ByteSink {
180 public:
ZeroCopyStreamByteSink(io::ZeroCopyOutputStream * stream)181 explicit ZeroCopyStreamByteSink(io::ZeroCopyOutputStream* stream)
182 : stream_(stream), buffer_size_(0) {}
183 ~ZeroCopyStreamByteSink();
184
185 virtual void Append(const char* bytes, size_t len);
186
187 private:
188 io::ZeroCopyOutputStream* stream_;
189 void* buffer_;
190 int buffer_size_;
191
192 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ZeroCopyStreamByteSink);
193 };
194 } // namespace internal
195
196 } // namespace util
197 } // namespace protobuf
198
199 } // namespace google
200 #endif // GOOGLE_PROTOBUF_UTIL_JSON_UTIL_H__
201