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, though only UTC (as indicated by "Z") is presently supported. 107 // 108 // For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 109 // 01:30 UTC on January 15, 2017. 110 // 111 // In JavaScript, one can convert a Date object to this format using the 112 // standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString] 113 // method. In Python, a standard `datetime.datetime` object can be converted 114 // to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) 115 // with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one 116 // can use the Joda Time's [`ISODateTimeFormat.dateTime()`]( 117 // http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()) 118 // to obtain a formatter capable of generating timestamps in this format. 119 // 120 // 121 message Timestamp { 122 123 // Represents seconds of UTC time since Unix epoch 124 // 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 125 // 9999-12-31T23:59:59Z inclusive. 126 int64 seconds = 1; 127 128 // Non-negative fractions of a second at nanosecond resolution. Negative 129 // second values with fractions must still have non-negative nanos values 130 // that count forward in time. Must be from 0 to 999,999,999 131 // inclusive. 132 int32 nanos = 2; 133 } 134
