protobuf/json/json.h

0001 // Protocol Buffers - Google's data interchange format
0002 // Copyright 2008 Google Inc.  All rights reserved.
0003 //
0004 // Use of this source code is governed by a BSD-style
0005 // license that can be found in the LICENSE file or at
0006 // https://developers.google.com/open-source/licenses/bsd
0007
0008 // Utility functions to convert between protobuf binary format and proto3 JSON
0009 // format.
0010 #ifndef GOOGLE_PROTOBUF_JSON_JSON_H__
0011 #define GOOGLE_PROTOBUF_JSON_JSON_H__
0012
0013 #include <string>
0014
0015 #include "absl/status/status.h"
0016 #include "absl/strings/string_view.h"
0017 #include "google/protobuf/message.h"
0018 #include "google/protobuf/util/type_resolver.h"
0019
0020 // Must be included last.
0021 #include "google/protobuf/port_def.inc"
0022
0023 namespace google {
0024 namespace protobuf {
0025 namespace json {
0026 struct ParseOptions {
0027   // Whether to ignore unknown JSON fields during parsing
0028   bool ignore_unknown_fields = false;
0029
0030   // If true, when a lowercase enum value fails to parse, try convert it to
0031   // UPPER_CASE and see if it matches a valid enum.
0032   // WARNING: This option exists only to preserve legacy behavior. Avoid using
0033   // this option. If your enum needs to support different casing, consider using
0034   // allow_alias instead.
0035   bool case_insensitive_enum_parsing = false;
0036 };
0037
0038 struct PrintOptions {
0039   // Whether to add spaces, line breaks and indentation to make the JSON output
0040   // easy to read.
0041   bool add_whitespace = false;
0042   // Whether to always print fields which do not support presence if they would
0043   // otherwise be omitted, namely:
0044   // - Implicit presence fields set to their 0 value
0045   // - Empty lists and maps
0046   bool always_print_fields_with_no_presence = false;
0047   // Whether to always print enums as ints. By default they are rendered as
0048   // strings.
0049   bool always_print_enums_as_ints = false;
0050   // Whether to preserve proto field names
0051   bool preserve_proto_field_names = false;
0052   // If set, int64 values that can be represented exactly as a double are
0053   // printed without quotes.
0054   bool unquote_int64_if_possible = false;
0055 };
0056
0057 // Converts from protobuf message to JSON and appends it to |output|. This is a
0058 // simple wrapper of BinaryToJsonString(). It will use the DescriptorPool of the
0059 // passed-in message to resolve Any types.
0060 //
0061 // Please note that non-OK statuses are not a stable output of this API and
0062 // subject to change without notice.
0063 PROTOBUF_EXPORT absl::Status MessageToJsonString(const Message& message,
0064                                                  std::string* output,
0065                                                  const PrintOptions& options);
0066
0067 inline absl::Status MessageToJsonString(const Message& message,
0068                                         std::string* output) {
0069   return MessageToJsonString(message, output, PrintOptions());
0070 }
0071
0072 // Converts from protobuf message to JSON and appends it to |json_output|. This
0073 // is a simple wrapper of BinaryToJsonStream(). It will use the DescriptorPool
0074 // of the passed-in message to resolve Any types.
0075 //
0076 // Please note that non-OK statuses are not a stable output of this API and
0077 // subject to change without notice.
0078 PROTOBUF_EXPORT absl::Status MessageToJsonStream(
0079     const Message& message, io::ZeroCopyOutputStream* json_output,
0080     const PrintOptions& options);
0081
0082 inline absl::Status MessageToJsonStream(const Message& message,
0083                                         io::ZeroCopyOutputStream* json_output) {
0084   return MessageToJsonStream(message, json_output, PrintOptions());
0085 }
0086
0087 // Converts from JSON string to protobuf message. This works equivalently to
0088 // JsonToBinaryStream(). It will use the DescriptorPool of the passed-in
0089 // message to resolve Any types.
0090 //
0091 // Please note that non-OK statuses are not a stable output of this API and
0092 // subject to change without notice.
0093 PROTOBUF_EXPORT absl::Status JsonStringToMessage(absl::string_view input,
0094                                                  Message* message,
0095                                                  const ParseOptions& options);
0096
0097 inline absl::Status JsonStringToMessage(absl::string_view input,
0098                                         Message* message) {
0099   return JsonStringToMessage(input, message, ParseOptions());
0100 }
0101
0102 // Converts from JSON stream to protobuf message. Similar to JsonStringToMessage
0103 // but with input stream.
0104 //
0105 // Please note that non-OK statuses are not a stable output of this API and
0106 // subject to change without notice.
0107 PROTOBUF_EXPORT absl::Status JsonStreamToMessage(io::ZeroCopyInputStream* input,
0108                                                  Message* message,
0109                                                  const ParseOptions& options);
0110
0111 inline absl::Status JsonStreamToMessage(io::ZeroCopyInputStream* input,
0112                                         Message* message) {
0113   return JsonStreamToMessage(input, message, ParseOptions());
0114 }
0115
0116 // Converts protobuf binary data to JSON.
0117 // The conversion will fail if:
0118 //   1. TypeResolver fails to resolve a type.
0119 //   2. input is not valid protobuf wire format, or conflicts with the type
0120 //      information returned by TypeResolver.
0121 // Note that unknown fields will be discarded silently.
0122 //
0123 // Please note that non-OK statuses are not a stable output of this API and
0124 // subject to change without notice.
0125 PROTOBUF_EXPORT absl::Status BinaryToJsonStream(
0126     google::protobuf::util::TypeResolver* resolver, const std::string& type_url,
0127     io::ZeroCopyInputStream* binary_input,
0128     io::ZeroCopyOutputStream* json_output, const PrintOptions& options);
0129
0130 inline absl::Status BinaryToJsonStream(google::protobuf::util::TypeResolver* resolver,
0131                                        const std::string& type_url,
0132                                        io::ZeroCopyInputStream* binary_input,
0133                                        io::ZeroCopyOutputStream* json_output) {
0134   return BinaryToJsonStream(resolver, type_url, binary_input, json_output,
0135                             PrintOptions());
0136 }
0137
0138 PROTOBUF_EXPORT absl::Status BinaryToJsonString(
0139     google::protobuf::util::TypeResolver* resolver, const std::string& type_url,
0140     const std::string& binary_input, std::string* json_output,
0141     const PrintOptions& options);
0142
0143 inline absl::Status BinaryToJsonString(google::protobuf::util::TypeResolver* resolver,
0144                                        const std::string& type_url,
0145                                        const std::string& binary_input,
0146                                        std::string* json_output) {
0147   return BinaryToJsonString(resolver, type_url, binary_input, json_output,
0148                             PrintOptions());
0149 }
0150
0151 // Converts JSON data to protobuf binary format.
0152 // The conversion will fail if:
0153 //   1. TypeResolver fails to resolve a type.
0154 //   2. input is not valid JSON format, or conflicts with the type
0155 //      information returned by TypeResolver.
0156 //
0157 // Please note that non-OK statuses are not a stable output of this API and
0158 // subject to change without notice.
0159 PROTOBUF_EXPORT absl::Status JsonToBinaryStream(
0160     google::protobuf::util::TypeResolver* resolver, const std::string& type_url,
0161     io::ZeroCopyInputStream* json_input,
0162     io::ZeroCopyOutputStream* binary_output, const ParseOptions& options);
0163
0164 inline absl::Status JsonToBinaryStream(
0165     google::protobuf::util::TypeResolver* resolver, const std::string& type_url,
0166     io::ZeroCopyInputStream* json_input,
0167     io::ZeroCopyOutputStream* binary_output) {
0168   return JsonToBinaryStream(resolver, type_url, json_input, binary_output,
0169                             ParseOptions());
0170 }
0171
0172 PROTOBUF_EXPORT absl::Status JsonToBinaryString(
0173     google::protobuf::util::TypeResolver* resolver, const std::string& type_url,
0174     absl::string_view json_input, std::string* binary_output,
0175     const ParseOptions& options);
0176
0177 inline absl::Status JsonToBinaryString(google::protobuf::util::TypeResolver* resolver,
0178                                        const std::string& type_url,
0179                                        absl::string_view json_input,
0180                                        std::string* binary_output) {
0181   return JsonToBinaryString(resolver, type_url, json_input, binary_output,
0182                             ParseOptions());
0183 }
0184 }  // namespace json
0185 }  // namespace protobuf
0186 }  // namespace google
0187
0188 #include "google/protobuf/port_undef.inc"
0189
0190 #endif  // GOOGLE_PROTOBUF_JSON_JSON_H__