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
JsonPrintOptionsJsonPrintOptions65 JsonPrintOptions() : add_whitespace(false),
66 always_print_primitive_fields(false) {
67 }
68 };
69
70 // DEPRECATED. Use JsonPrintOptions instead.
71 typedef JsonPrintOptions JsonOptions;
72
73 // Converts from protobuf message to JSON. This is a simple wrapper of
74 // BinaryToJsonString(). It will use the DescriptorPool of the passed-in
75 // message to resolve Any types.
76 LIBPROTOBUF_EXPORT util::Status MessageToJsonString(const Message& message,
77 string* output,
78 const JsonOptions& options);
79
MessageToJsonString(const Message & message,string * output)80 inline util::Status MessageToJsonString(const Message& message,
81 string* output) {
82 return MessageToJsonString(message, output, JsonOptions());
83 }
84
85 // Converts from JSON to protobuf message. This is a simple wrapper of
86 // JsonStringToBinary(). It will use the DescriptorPool of the passed-in
87 // message to resolve Any types.
88 LIBPROTOBUF_EXPORT util::Status JsonStringToMessage(const string& input,
89 Message* message,
90 const JsonParseOptions& options);
91
JsonStringToMessage(const string & input,Message * message)92 inline util::Status JsonStringToMessage(const string& input,
93 Message* message) {
94 return JsonStringToMessage(input, message, JsonParseOptions());
95 }
96
97 // Converts protobuf binary data to JSON.
98 // The conversion will fail if:
99 // 1. TypeResolver fails to resolve a type.
100 // 2. input is not valid protobuf wire format, or conflicts with the type
101 // information returned by TypeResolver.
102 // Note that unknown fields will be discarded silently.
103 LIBPROTOBUF_EXPORT util::Status BinaryToJsonStream(
104 TypeResolver* resolver,
105 const string& type_url,
106 io::ZeroCopyInputStream* binary_input,
107 io::ZeroCopyOutputStream* json_output,
108 const JsonPrintOptions& options);
109
BinaryToJsonStream(TypeResolver * resolver,const string & type_url,io::ZeroCopyInputStream * binary_input,io::ZeroCopyOutputStream * json_output)110 inline util::Status BinaryToJsonStream(
111 TypeResolver* resolver, const string& type_url,
112 io::ZeroCopyInputStream* binary_input,
113 io::ZeroCopyOutputStream* json_output) {
114 return BinaryToJsonStream(resolver, type_url, binary_input, json_output,
115 JsonPrintOptions());
116 }
117
118 LIBPROTOBUF_EXPORT util::Status BinaryToJsonString(
119 TypeResolver* resolver,
120 const string& type_url,
121 const string& binary_input,
122 string* json_output,
123 const JsonPrintOptions& options);
124
BinaryToJsonString(TypeResolver * resolver,const string & type_url,const string & binary_input,string * json_output)125 inline util::Status BinaryToJsonString(TypeResolver* resolver,
126 const string& type_url,
127 const string& binary_input,
128 string* json_output) {
129 return BinaryToJsonString(resolver, type_url, binary_input, json_output,
130 JsonPrintOptions());
131 }
132
133 // Converts JSON data to protobuf binary format.
134 // The conversion will fail if:
135 // 1. TypeResolver fails to resolve a type.
136 // 2. input is not valid JSON format, or conflicts with the type
137 // information returned by TypeResolver.
138 LIBPROTOBUF_EXPORT util::Status JsonToBinaryStream(
139 TypeResolver* resolver,
140 const string& type_url,
141 io::ZeroCopyInputStream* json_input,
142 io::ZeroCopyOutputStream* binary_output,
143 const JsonParseOptions& options);
144
JsonToBinaryStream(TypeResolver * resolver,const string & type_url,io::ZeroCopyInputStream * json_input,io::ZeroCopyOutputStream * binary_output)145 inline util::Status JsonToBinaryStream(
146 TypeResolver* resolver,
147 const string& type_url,
148 io::ZeroCopyInputStream* json_input,
149 io::ZeroCopyOutputStream* binary_output) {
150 return JsonToBinaryStream(resolver, type_url, json_input, binary_output,
151 JsonParseOptions());
152 }
153
154 LIBPROTOBUF_EXPORT util::Status JsonToBinaryString(
155 TypeResolver* resolver,
156 const string& type_url,
157 const string& json_input,
158 string* binary_output,
159 const JsonParseOptions& options);
160
JsonToBinaryString(TypeResolver * resolver,const string & type_url,const string & json_input,string * binary_output)161 inline util::Status JsonToBinaryString(
162 TypeResolver* resolver,
163 const string& type_url,
164 const string& json_input,
165 string* binary_output) {
166 return JsonToBinaryString(resolver, type_url, json_input, binary_output,
167 JsonParseOptions());
168 }
169
170 namespace internal {
171 // Internal helper class. Put in the header so we can write unit-tests for it.
172 class LIBPROTOBUF_EXPORT ZeroCopyStreamByteSink : public strings::ByteSink {
173 public:
ZeroCopyStreamByteSink(io::ZeroCopyOutputStream * stream)174 explicit ZeroCopyStreamByteSink(io::ZeroCopyOutputStream* stream)
175 : stream_(stream) {}
176
177 virtual void Append(const char* bytes, size_t len);
178
179 private:
180 io::ZeroCopyOutputStream* stream_;
181
182 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ZeroCopyStreamByteSink);
183 };
184 } // namespace internal
185
186 } // namespace util
187 } // namespace protobuf
188
189 } // namespace google
190 #endif // GOOGLE_PROTOBUF_UTIL_JSON_UTIL_H__
191