diff options
Diffstat (limited to 'csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs')
| -rw-r--r-- | csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs | 111 |
1 files changed, 107 insertions, 4 deletions
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs b/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs index 0dac4403..33c814ef 100644 --- a/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs +++ b/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs @@ -11,10 +11,12 @@ namespace Google.Protobuf.WellKnownTypes { namespace Proto { + /// <summary>Holder for reflection information generated from google/protobuf/field_mask.proto</summary> [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] public static partial class FieldMask { #region Descriptor + /// <summary>File descriptor for google/protobuf/field_mask.proto</summary> public static pbr::FileDescriptor Descriptor { get { return descriptor; } } @@ -23,10 +25,10 @@ namespace Google.Protobuf.WellKnownTypes { static FieldMask() { byte[] descriptorData = global::System.Convert.FromBase64String( string.Concat( - "CiBnb29nbGUvcHJvdG9idWYvZmllbGRfbWFzay5wcm90bxIPZ29vZ2xlLnBy", - "b3RvYnVmIhoKCUZpZWxkTWFzaxINCgVwYXRocxgBIAMoCUJOChNjb20uZ29v", - "Z2xlLnByb3RvYnVmQg5GaWVsZE1hc2tQcm90b1ABogIDR1BCqgIeR29vZ2xl", - "LlByb3RvYnVmLldlbGxLbm93blR5cGVzYgZwcm90bzM=")); + "CiBnb29nbGUvcHJvdG9idWYvZmllbGRfbWFzay5wcm90bxIPZ29vZ2xlLnBy", + "b3RvYnVmIhoKCUZpZWxkTWFzaxINCgVwYXRocxgBIAMoCUJRChNjb20uZ29v", + "Z2xlLnByb3RvYnVmQg5GaWVsZE1hc2tQcm90b1ABoAEBogIDR1BCqgIeR29v", + "Z2xlLlByb3RvYnVmLldlbGxLbm93blR5cGVzYgZwcm90bzM=")); descriptor = pbr::FileDescriptor.InternalBuildGeneratedFileFrom(descriptorData, new pbr::FileDescriptor[] { }, new pbr::GeneratedCodeInfo(null, new pbr::GeneratedCodeInfo[] { @@ -38,6 +40,103 @@ namespace Google.Protobuf.WellKnownTypes { } } #region Messages + /// <summary> + /// `FieldMask` represents a set of symbolic field paths, for example: + /// paths: "f.a" + /// paths: "f.b.d" + /// Here `f` represents a field in some root message, `a` and `b` + /// fields in the message found in `f`, and `d` a field found in the + /// message in `f.b`. + /// Field masks are used to specify a subset of fields that should be + /// returned by a get operation or modified by an update operation. + /// Field masks also have a custom JSON encoding (see below). + /// # Field Masks in Projections + /// When used in the context of a projection, a response message or + /// sub-message is filtered by the API to only contain those fields as + /// specified in the mask. For example, if the mask in the previous + /// example is applied to a response message as follows: + /// f { + /// a : 22 + /// b { + /// d : 1 + /// x : 2 + /// } + /// y : 13 + /// } + /// z: 8 + /// The result will not contain specific values for fields x,y and z + /// (there value will be set to the default, and omitted in proto text + /// output): + /// f { + /// a : 22 + /// b { + /// d : 1 + /// } + /// } + /// A repeated field is not allowed except at the last position of a + /// field mask. + /// If a FieldMask object is not present in a get operation, the + /// operation applies to all fields (as if a FieldMask of all fields + /// had been specified). + /// Note that a field mask does not necessarily applies to the + /// top-level response message. In case of a REST get operation, the + /// field mask applies directly to the response, but in case of a REST + /// list operation, the mask instead applies to each individual message + /// in the returned resource list. In case of a REST custom method, + /// other definitions may be used. Where the mask applies will be + /// clearly documented together with its declaration in the API. In + /// any case, the effect on the returned resource/resources is required + /// behavior for APIs. + /// # Field Masks in Update Operations + /// A field mask in update operations specifies which fields of the + /// targeted resource are going to be updated. The API is required + /// to only change the values of the fields as specified in the mask + /// and leave the others untouched. If a resource is passed in to + /// describe the updated values, the API ignores the values of all + /// fields not covered by the mask. + /// In order to reset a field's value to the default, the field must + /// be in the mask and set to the default value in the provided resource. + /// Hence, in order to reset all fields of a resource, provide a default + /// instance of the resource and set all fields in the mask, or do + /// not provide a mask as described below. + /// If a field mask is not present on update, the operation applies to + /// all fields (as if a field mask of all fields has been specified). + /// Note that in the presence of schema evolution, this may mean that + /// fields the client does not know and has therefore not filled into + /// the request will be reset to their default. If this is unwanted + /// behavior, a specific service may require a client to always specify + /// a field mask, producing an error if not. + /// As with get operations, the location of the resource which + /// describes the updated values in the request message depends on the + /// operation kind. In any case, the effect of the field mask is + /// required to be honored by the API. + /// ## Considerations for HTTP REST + /// The HTTP kind of an update operation which uses a field mask must + /// be set to PATCH instead of PUT in order to satisfy HTTP semantics + /// (PUT must only be used for full updates). + /// # JSON Encoding of Field Masks + /// In JSON, a field mask is encoded as a single string where paths are + /// separated by a comma. Fields name in each path are converted + /// to/from lower-camel naming conventions. + /// As an example, consider the following message declarations: + /// message Profile { + /// User user = 1; + /// Photo photo = 2; + /// } + /// message User { + /// string display_name = 1; + /// string address = 2; + /// } + /// In proto a field mask for `Profile` may look as such: + /// mask { + /// paths: "user.display_name" + /// paths: "photo" + /// } + /// In JSON, the same mask is represented as below: + /// { + /// mask: "user.displayName,photo" + /// } + /// </summary> [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] public sealed partial class FieldMask : pb::IMessage<FieldMask> { private static readonly pb::MessageParser<FieldMask> _parser = new pb::MessageParser<FieldMask>(() => new FieldMask()); @@ -65,10 +164,14 @@ namespace Google.Protobuf.WellKnownTypes { return new FieldMask(this); } + /// <summary>Field number for the "paths" field.</summary> public const int PathsFieldNumber = 1; private static readonly pb::FieldCodec<string> _repeated_paths_codec = pb::FieldCodec.ForString(10); private readonly pbc::RepeatedField<string> paths_ = new pbc::RepeatedField<string>(); + /// <summary> + /// The set of field mask paths. + /// </summary> public pbc::RepeatedField<string> Paths { get { return paths_; } } |