diff options
Diffstat (limited to 'csharp/src/Google.Protobuf/WellKnownTypes')
8 files changed, 88 insertions, 0 deletions
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Any.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Any.cs index 4a704018..64cbd33d 100644 --- a/csharp/src/Google.Protobuf/WellKnownTypes/Any.cs +++ b/csharp/src/Google.Protobuf/WellKnownTypes/Any.cs @@ -43,25 +43,30 @@ namespace Google.Protobuf.WellKnownTypes { /// <summary> /// `Any` contains an arbitrary serialized message along with a URL /// that describes the type of the serialized message. + /// /// JSON /// ==== /// The JSON representation of an `Any` value uses the regular /// representation of the deserialized, embedded message, with an /// additional field `@type` which contains the type URL. Example: + /// /// package google.profile; /// message Person { /// string first_name = 1; /// string last_name = 2; /// } + /// /// { /// "@type": "type.googleapis.com/google.profile.Person", /// "firstName": <string>, /// "lastName": <string> /// } + /// /// If the embedded message type is well-known and has a custom JSON /// representation, that representation will be embedded adding a field /// `value` which holds the custom JSON in addition to the the `@type` /// field. Example (for message [google.protobuf.Duration][google.protobuf.Duration]): + /// /// { /// "@type": "type.googleapis.com/google.protobuf.Duration", /// "value": "1.212s" @@ -101,8 +106,10 @@ namespace Google.Protobuf.WellKnownTypes { /// <summary> /// A URL/resource name whose content describes the type of the /// serialized message. + /// /// For URLs which use the schema `http`, `https`, or no schema, the /// following restrictions and interpretations apply: + /// /// * If no schema is provided, `https` is assumed. /// * The last segment of the URL's path must represent the fully /// qualified name of the type (as in `path/google.protobuf.Duration`). @@ -113,6 +120,7 @@ namespace Google.Protobuf.WellKnownTypes { /// lookup. Therefore, binary compatibility needs to be preserved /// on changes to types. (Use versioned type names to manage /// breaking changes.) + /// /// Schemas other than `http`, `https` (or the empty schema) might be /// used with implementation specific semantics. /// </summary> diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Api.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Api.cs index 2c64314d..899613f9 100644 --- a/csharp/src/Google.Protobuf/WellKnownTypes/Api.cs +++ b/csharp/src/Google.Protobuf/WellKnownTypes/Api.cs @@ -139,12 +139,14 @@ namespace Google.Protobuf.WellKnownTypes { /// outlined below. If the field is not empty, the version in the /// package name will be verified to be consistent with what is /// provided here. + /// /// The versioning schema uses [semantic /// versioning](http://semver.org) where the major version number /// indicates a breaking change and the minor version an additive, /// non-breaking change. Both version numbers are signals to users /// what to expect from different versions, and should be carefully /// chosen based on the product plan. + /// /// The major version is also reflected in the package name of the /// API, which must end in `v<major-version>`, as in /// `google.feature.v1`. For major versions 0 and 1, the suffix can @@ -629,16 +631,21 @@ namespace Google.Protobuf.WellKnownTypes { /// Declares an API to be included in this API. The including API must /// redeclare all the methods from the included API, but documentation /// and options are inherited as follows: + /// /// - If after comment and whitespace stripping, the documentation /// string of the redeclared method is empty, it will be inherited /// from the original method. + /// /// - Each annotation belonging to the service config (http, /// visibility) which is not set in the redeclared method will be /// inherited. + /// /// - If an http annotation is inherited, the path pattern will be /// modified as follows. Any version prefix will be replaced by the /// version of the including API plus the [root][] path if specified. + /// /// Example of a simple mixin: + /// /// package google.acl.v1; /// service AccessControl { /// // Get the underlying ACL object. @@ -646,25 +653,31 @@ namespace Google.Protobuf.WellKnownTypes { /// option (google.api.http).get = "/v1/{resource=**}:getAcl"; /// } /// } + /// /// package google.storage.v2; /// service Storage { /// // (-- see AccessControl.GetAcl --) /// rpc GetAcl(GetAclRequest) returns (Acl); + /// /// // Get a data record. /// rpc GetData(GetDataRequest) returns (Data) { /// option (google.api.http).get = "/v2/{resource=**}"; /// } /// } + /// /// Example of a mixin configuration: + /// /// apis: /// - name: google.storage.v2.Storage /// mixins: /// - name: google.acl.v1.AccessControl + /// /// The mixin construct implies that all methods in `AccessControl` are /// also declared with same name and request/response types in /// `Storage`. A documentation generator or annotation processor will /// see the effective `Storage.GetAcl` method after inherting /// documentation and annotations as follows: + /// /// service Storage { /// // Get the underlying ACL object. /// rpc GetAcl(GetAclRequest) returns (Acl) { @@ -672,15 +685,20 @@ namespace Google.Protobuf.WellKnownTypes { /// } /// ... /// } + /// /// Note how the version in the path pattern changed from `v1` to `v2`. + /// /// If the `root` field in the mixin is specified, it should be a /// relative path under which inherited HTTP paths are placed. Example: + /// /// apis: /// - name: google.storage.v2.Storage /// mixins: /// - name: google.acl.v1.AccessControl /// root: acls + /// /// This implies the following inherited HTTP annotation: + /// /// service Storage { /// // Get the underlying ACL object. /// rpc GetAcl(GetAclRequest) returns (Acl) { diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Duration.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Duration.cs index 39251e2e..cc2dfd26 100644 --- a/csharp/src/Google.Protobuf/WellKnownTypes/Duration.cs +++ b/csharp/src/Google.Protobuf/WellKnownTypes/Duration.cs @@ -48,12 +48,16 @@ namespace Google.Protobuf.WellKnownTypes { /// or "month". It is related to Timestamp in that the difference between /// two Timestamp values is a Duration and it can be added or subtracted /// from a Timestamp. Range is approximately +-10,000 years. + /// /// Example 1: Compute Duration from two Timestamps in pseudo code. + /// /// Timestamp start = ...; /// Timestamp end = ...; /// Duration duration = ...; + /// /// duration.seconds = end.seconds - start.seconds; /// duration.nanos = end.nanos - start.nanos; + /// /// if (duration.seconds < 0 && duration.nanos > 0) { /// duration.seconds += 1; /// duration.nanos -= 1000000000; @@ -61,12 +65,16 @@ namespace Google.Protobuf.WellKnownTypes { /// duration.seconds -= 1; /// duration.nanos += 1000000000; /// } + /// /// Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. + /// /// Timestamp start = ...; /// Duration duration = ...; /// Timestamp end = ...; + /// /// end.seconds = start.seconds + duration.seconds; /// end.nanos = start.nanos + duration.nanos; + /// /// if (end.nanos < 0) { /// end.seconds -= 1; /// end.nanos += 1000000000; diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Empty.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Empty.cs index 18223a9e..f2d2de01 100644 --- a/csharp/src/Google.Protobuf/WellKnownTypes/Empty.cs +++ b/csharp/src/Google.Protobuf/WellKnownTypes/Empty.cs @@ -44,9 +44,11 @@ namespace Google.Protobuf.WellKnownTypes { /// A generic empty message that you can re-use to avoid defining duplicated /// empty messages in your APIs. A typical example is to use it as the request /// or the response type of an API method. For instance: + /// /// service Foo { /// rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); /// } + /// /// The JSON representation for `Empty` is empty JSON object `{}`. /// </summary> [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs b/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs index 33c814ef..e71e4af6 100644 --- a/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs +++ b/csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs @@ -42,19 +42,25 @@ 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 { @@ -64,20 +70,25 @@ namespace Google.Protobuf.WellKnownTypes { /// 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 @@ -87,18 +98,22 @@ namespace Google.Protobuf.WellKnownTypes { /// 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 @@ -106,19 +121,26 @@ namespace Google.Protobuf.WellKnownTypes { /// 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; @@ -127,12 +149,16 @@ namespace Google.Protobuf.WellKnownTypes { /// 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" /// } diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Struct.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Struct.cs index b2d7783c..8f8e917d 100644 --- a/csharp/src/Google.Protobuf/WellKnownTypes/Struct.cs +++ b/csharp/src/Google.Protobuf/WellKnownTypes/Struct.cs @@ -55,6 +55,7 @@ namespace Google.Protobuf.WellKnownTypes { /// <summary> /// `NullValue` is a singleton enumeration to represent the null value for the /// `Value` type union. + /// /// The JSON representation for `NullValue` is JSON `null`. /// </summary> public enum NullValue { @@ -74,6 +75,7 @@ namespace Google.Protobuf.WellKnownTypes { /// scripting languages like JS a struct is represented as an /// object. The details of that representation are described together /// with the proto support for the language. + /// /// The JSON representation for `Struct` is JSON object. /// </summary> [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] @@ -179,6 +181,7 @@ namespace Google.Protobuf.WellKnownTypes { /// null, a number, a string, a boolean, a recursive struct value, or a /// list of values. A producer of value is expected to set one of that /// variants, absence of any variant indicates an error. + /// /// The JSON representation for `Value` is JSON value. /// </summary> [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] @@ -491,6 +494,7 @@ namespace Google.Protobuf.WellKnownTypes { /// <summary> /// `ListValue` is a wrapper around a repeated field of values. + /// /// The JSON representation for `ListValue` is JSON array. /// </summary> [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Timestamp.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Timestamp.cs index f372f8fd..1044a683 100644 --- a/csharp/src/Google.Protobuf/WellKnownTypes/Timestamp.cs +++ b/csharp/src/Google.Protobuf/WellKnownTypes/Timestamp.cs @@ -53,30 +53,43 @@ namespace Google.Protobuf.WellKnownTypes { /// By restricting to that range, we ensure that we can convert to /// and from RFC 3339 date strings. /// See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt). + /// /// Example 1: Compute Timestamp from POSIX `time()`. + /// /// Timestamp timestamp; /// timestamp.set_seconds(time(NULL)); /// timestamp.set_nanos(0); + /// /// Example 2: Compute Timestamp from POSIX `gettimeofday()`. + /// /// struct timeval tv; /// gettimeofday(&tv, NULL); + /// /// Timestamp timestamp; /// timestamp.set_seconds(tv.tv_sec); /// timestamp.set_nanos(tv.tv_usec * 1000); + /// /// Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. + /// /// FILETIME ft; /// GetSystemTimeAsFileTime(&ft); /// UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; + /// /// // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z /// // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. /// Timestamp timestamp; /// timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); /// timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); + /// /// Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. + /// /// long millis = System.currentTimeMillis(); + /// /// Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) /// .setNanos((int) ((millis % 1000) * 1000000)).build(); + /// /// Example 5: Compute Timestamp from current time in Python. + /// /// now = time.time() /// seconds = int(now) /// nanos = int((now - seconds) * 10**9) diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Wrappers.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Wrappers.cs index d26395f8..7fdcb11e 100644 --- a/csharp/src/Google.Protobuf/WellKnownTypes/Wrappers.cs +++ b/csharp/src/Google.Protobuf/WellKnownTypes/Wrappers.cs @@ -52,6 +52,7 @@ namespace Google.Protobuf.WellKnownTypes { #region Messages /// <summary> /// Wrapper message for `double`. + /// /// The JSON representation for `DoubleValue` is JSON number. /// </summary> [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] @@ -162,6 +163,7 @@ namespace Google.Protobuf.WellKnownTypes { /// <summary> /// Wrapper message for `float`. + /// /// The JSON representation for `FloatValue` is JSON number. /// </summary> [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] @@ -272,6 +274,7 @@ namespace Google.Protobuf.WellKnownTypes { /// <summary> /// Wrapper message for `int64`. + /// /// The JSON representation for `Int64Value` is JSON string. /// </summary> [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] @@ -382,6 +385,7 @@ namespace Google.Protobuf.WellKnownTypes { /// <summary> /// Wrapper message for `uint64`. + /// /// The JSON representation for `UInt64Value` is JSON string. /// </summary> [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] @@ -492,6 +496,7 @@ namespace Google.Protobuf.WellKnownTypes { /// <summary> /// Wrapper message for `int32`. + /// /// The JSON representation for `Int32Value` is JSON number. /// </summary> [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] @@ -602,6 +607,7 @@ namespace Google.Protobuf.WellKnownTypes { /// <summary> /// Wrapper message for `uint32`. + /// /// The JSON representation for `UInt32Value` is JSON number. /// </summary> [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] @@ -712,6 +718,7 @@ namespace Google.Protobuf.WellKnownTypes { /// <summary> /// Wrapper message for `bool`. + /// /// The JSON representation for `BoolValue` is JSON `true` and `false`. /// </summary> [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] @@ -822,6 +829,7 @@ namespace Google.Protobuf.WellKnownTypes { /// <summary> /// Wrapper message for `string`. + /// /// The JSON representation for `StringValue` is JSON string. /// </summary> [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] @@ -932,6 +940,7 @@ namespace Google.Protobuf.WellKnownTypes { /// <summary> /// Wrapper message for `bytes`. + /// /// The JSON representation for `BytesValue` is JSON string. /// </summary> [global::System.Diagnostics.DebuggerNonUserCodeAttribute()] |