sync/protocol/unique_position.proto

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4 //
   5 // Protobuf representation of the UniquePosition class.
   6
   7 // Update proto_value_conversions{.h,.cc,_unittest.cc} if you change
   8 // any fields in this file.
   9
  10 syntax = "proto2";
  11
  12 option optimize_for = LITE_RUNTIME;
  13 option retain_unknown_fields = true;
  14
  15 package sync_pb;
  16
  17 // A UniquePosition is a string of bytes.
  18 //
  19 // Unique positions are unique per-item, since they are guaranteed to end with a
  20 // fixed-length suffix that is unique per-item.  The position string may not end
  21 // with a '\0' byte.
  22 //
  23 // Prior to the suffix is a series of arbitrary bytes of arbitrary length.
  24 // Items under the same parent are positioned relative to each other by a
  25 // lexicographic comparison of their UniquePosition values.
  26 message UniquePosition {
  27   // The uncompressed string of bytes representing the position.
  28   optional bytes value = 1;
  29
  30   // The client may choose to write a compressed position to this field instead
  31   // of populating the 'value' above.  If it chooses to use compression, the
  32   // 'value' field above must be empty.  The position value will be compressed
  33   // with gzip and stored in the compressed_value field.  The position's
  34   // uncompressed length must be specified and written to the
  35   // uncompressed_length field.
  36   optional bytes compressed_value = 2;
  37   optional uint64 uncompressed_length = 3;
  38
  39   // This encoding uses compression scheme designed especially for unique
  40   // positions.  It has the property that X < Y precisely when Compressed(X) <
  41   // Compressed(Y), which is very useful when the most common operation is to
  42   // compare these positions against each other.  Their values may remain
  43   // compressed in memory.
  44   //
  45   // The compression scheme is implemented and documented in
  46   // sync/internal_api/base/unique_position.cc.
  47   //
  48   // As of M30, this is the preferred encoding.  Newer clients may continue to
  49   // populate the 'value' and 'compressed_value' fields to ensure backwards
  50   // compatibility, but they will always try to read from this field first.
  51   optional bytes custom_compressed_v1 = 4;
  52 }