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 JSON to protobuf message. This works equivalently to
0073 // JsonToBinaryStream(). It will use the DescriptorPool of the passed-in
0074 // 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 JsonStringToMessage(absl::string_view input,
0079                                                  Message* message,
0080                                                  const ParseOptions& options);
0081
0082 inline absl::Status JsonStringToMessage(absl::string_view input,
0083                                         Message* message) {
0084   return JsonStringToMessage(input, message, ParseOptions());
0085 }
0086
0087 // Converts protobuf binary data to JSON.
0088 // The conversion will fail if:
0089 //   1. TypeResolver fails to resolve a type.
0090 //   2. input is not valid protobuf wire format, or conflicts with the type
0091 //      information returned by TypeResolver.
0092 // Note that unknown fields will be discarded silently.
0093 //
0094 // Please note that non-OK statuses are not a stable output of this API and
0095 // subject to change without notice.
0096 PROTOBUF_EXPORT absl::Status BinaryToJsonStream(
0097     google::protobuf::util::TypeResolver* resolver, const std::string& type_url,
0098     io::ZeroCopyInputStream* binary_input,
0099     io::ZeroCopyOutputStream* json_output, const PrintOptions& options);
0100
0101 inline absl::Status BinaryToJsonStream(google::protobuf::util::TypeResolver* resolver,
0102                                        const std::string& type_url,
0103                                        io::ZeroCopyInputStream* binary_input,
0104                                        io::ZeroCopyOutputStream* json_output) {
0105   return BinaryToJsonStream(resolver, type_url, binary_input, json_output,
0106                             PrintOptions());
0107 }
0108
0109 PROTOBUF_EXPORT absl::Status BinaryToJsonString(
0110     google::protobuf::util::TypeResolver* resolver, const std::string& type_url,
0111     const std::string& binary_input, std::string* json_output,
0112     const PrintOptions& options);
0113
0114 inline absl::Status BinaryToJsonString(google::protobuf::util::TypeResolver* resolver,
0115                                        const std::string& type_url,
0116                                        const std::string& binary_input,
0117                                        std::string* json_output) {
0118   return BinaryToJsonString(resolver, type_url, binary_input, json_output,
0119                             PrintOptions());
0120 }
0121
0122 // Converts JSON data to protobuf binary format.
0123 // The conversion will fail if:
0124 //   1. TypeResolver fails to resolve a type.
0125 //   2. input is not valid JSON format, or conflicts with the type
0126 //      information returned by TypeResolver.
0127 //
0128 // Please note that non-OK statuses are not a stable output of this API and
0129 // subject to change without notice.
0130 PROTOBUF_EXPORT absl::Status JsonToBinaryStream(
0131     google::protobuf::util::TypeResolver* resolver, const std::string& type_url,
0132     io::ZeroCopyInputStream* json_input,
0133     io::ZeroCopyOutputStream* binary_output, const ParseOptions& options);
0134
0135 inline absl::Status JsonToBinaryStream(
0136     google::protobuf::util::TypeResolver* resolver, const std::string& type_url,
0137     io::ZeroCopyInputStream* json_input,
0138     io::ZeroCopyOutputStream* binary_output) {
0139   return JsonToBinaryStream(resolver, type_url, json_input, binary_output,
0140                             ParseOptions());
0141 }
0142
0143 PROTOBUF_EXPORT absl::Status JsonToBinaryString(
0144     google::protobuf::util::TypeResolver* resolver, const std::string& type_url,
0145     absl::string_view json_input, std::string* binary_output,
0146     const ParseOptions& options);
0147
0148 inline absl::Status JsonToBinaryString(google::protobuf::util::TypeResolver* resolver,
0149                                        const std::string& type_url,
0150                                        absl::string_view json_input,
0151                                        std::string* binary_output) {
0152   return JsonToBinaryString(resolver, type_url, json_input, binary_output,
0153                             ParseOptions());
0154 }
0155 }  // namespace json
0156 }  // namespace protobuf
0157 }  // namespace google
0158
0159 #include "google/protobuf/port_undef.inc"
0160
0161 #endif  // GOOGLE_PROTOBUF_JSON_JSON_H__