vendor/github.com/golang/protobuf/ptypes/timestamp/timestamp.proto

   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 syntax = "proto3";
  32
  33 package google.protobuf;
  34
  35 option csharp_namespace = "Google.Protobuf.WellKnownTypes";
  36 option cc_enable_arenas = true;
  37 option go_package = "github.com/golang/protobuf/ptypes/timestamp";
  38 option java_package = "com.google.protobuf";
  39 option java_outer_classname = "TimestampProto";
  40 option java_multiple_files = true;
  41 option objc_class_prefix = "GPB";
  42
  43 // A Timestamp represents a point in time independent of any time zone
  44 // or calendar, represented as seconds and fractions of seconds at
  45 // nanosecond resolution in UTC Epoch time. It is encoded using the
  46 // Proleptic Gregorian Calendar which extends the Gregorian calendar
  47 // backwards to year one. It is encoded assuming all minutes are 60
  48 // seconds long, i.e. leap seconds are "smeared" so that no leap second
  49 // table is needed for interpretation. Range is from
  50 // 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.
  51 // By restricting to that range, we ensure that we can convert to
  52 // and from  RFC 3339 date strings.
  53 // See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt).
  54 //
  55 // # Examples
  56 //
  57 // Example 1: Compute Timestamp from POSIX `time()`.
  58 //
  59 //     Timestamp timestamp;
  60 //     timestamp.set_seconds(time(NULL));
  61 //     timestamp.set_nanos(0);
  62 //
  63 // Example 2: Compute Timestamp from POSIX `gettimeofday()`.
  64 //
  65 //     struct timeval tv;
  66 //     gettimeofday(&tv, NULL);
  67 //
  68 //     Timestamp timestamp;
  69 //     timestamp.set_seconds(tv.tv_sec);
  70 //     timestamp.set_nanos(tv.tv_usec * 1000);
  71 //
  72 // Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
  73 //
  74 //     FILETIME ft;
  75 //     GetSystemTimeAsFileTime(&ft);
  76 //     UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
  77 //
  78 //     // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
  79 //     // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
  80 //     Timestamp timestamp;
  81 //     timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
  82 //     timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
  83 //
  84 // Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
  85 //
  86 //     long millis = System.currentTimeMillis();
  87 //
  88 //     Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
  89 //         .setNanos((int) ((millis % 1000) * 1000000)).build();
  90 //
  91 //
  92 // Example 5: Compute Timestamp from current time in Python.
  93 //
  94 //     timestamp = Timestamp()
  95 //     timestamp.GetCurrentTime()
  96 //
  97 // # JSON Mapping
  98 //
  99 // In JSON format, the Timestamp type is encoded as a string in the
 100 // [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
 101 // format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
 102 // where {year} is always expressed using four digits while {month}, {day},
 103 // {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
 104 // seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
 105 // are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
 106 // is required. A proto3 JSON serializer should always use UTC (as indicated by
 107 // "Z") when printing the Timestamp type and a proto3 JSON parser should be
 108 // able to accept both UTC and other timezones (as indicated by an offset).
 109 //
 110 // For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
 111 // 01:30 UTC on January 15, 2017.
 112 //
 113 // In JavaScript, one can convert a Date object to this format using the
 114 // standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString]
 115 // method. In Python, a standard `datetime.datetime` object can be converted
 116 // to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime)
 117 // with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one
 118 // can use the Joda Time's [`ISODateTimeFormat.dateTime()`](
 119 // http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime--
 120 // ) to obtain a formatter capable of generating timestamps in this format.
 121 //
 122 //
 123 message Timestamp {
 124
 125   // Represents seconds of UTC time since Unix epoch
 126   // 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to
 127   // 9999-12-31T23:59:59Z inclusive.
 128   int64 seconds = 1;
 129
 130   // Non-negative fractions of a second at nanosecond resolution. Negative
 131   // second values with fractions must still have non-negative nanos values
 132   // that count forward in time. Must be from 0 to 999,999,999
 133   // inclusive.
 134   int32 nanos = 2;
 135 }