chromium/components/sync/base/data_type.h

// Copyright 2012 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef COMPONENTS_SYNC_BASE_DATA_TYPE_H_
#define COMPONENTS_SYNC_BASE_DATA_TYPE_H_

#include <iosfwd>
#include <map>
#include <memory>
#include <string>

#include "base/containers/enum_set.h"
#include "base/values.h"

namespace sync_pb {
class EntitySpecifics;
}

namespace syncer {

// Enumerate the various item subtypes that are supported by sync.
// Each sync object is expected to have an immutable object type.
// An object's type is inferred from the type of data it holds.
//
// A Java counterpart will be generated for this enum.
// GENERATED_JAVA_ENUM_PACKAGE: org.chromium.components.sync
//
// |kDataTypeInfoMap| struct entries are in the same order as their definition
// in DataType enum. When you make changes in DataType enum, don't forget to
// update the |kDataTypeInfoMap| struct in data_type.cc and also the
// SyncDataType histogram suffix in histograms.xml
enum DataType { … };

DataTypeSet;

constexpr int GetNumDataTypes() { … }

// A version of the DataType enum for use in histograms. DataType does not
// have stable values (e.g. new ones may be inserted in the middle), so it can't
// be recorded directly.
// Instead of using entries from this enum directly, you'll usually want to get
// them via DataTypeHistogramValue(data_type).
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused. When you add a new entry or when you
// deprecate an existing one, also update SyncDataTypes in enums.xml and
// SyncDataType suffix in histograms.xml.
// LINT.IfChange(SyncDataTypes)
enum class DataTypeForHistograms { … };
// LINT.ThenChange(/tools/metrics/histograms/metadata/sync/enums.xml:SyncDataTypes)

// Used to mark the type of EntitySpecifics that has no actual data.
void AddDefaultFieldValue(DataType type, sync_pb::EntitySpecifics* specifics);

// Extract the data type from an EntitySpecifics field. DataType is a
// local concept: the enum is not in the protocol.
DataType GetDataTypeFromSpecifics(const sync_pb::EntitySpecifics& specifics);

// Protocol types are those types that have actual protocol buffer
// representations. This is the same as the "real" data types, i.e. all types
// except UNSPECIFIED.
constexpr DataTypeSet ProtocolTypes() { … }

// These are the normal user-controlled types. This is to distinguish from
// ControlTypes which are always enabled.  Note that some of these share a
// preference flag, so not all of them are individually user-selectable.
constexpr DataTypeSet UserTypes() { … }

// User types which are not user-controlled.
constexpr DataTypeSet AlwaysPreferredUserTypes() { … }

// User types which are always encrypted.
constexpr DataTypeSet AlwaysEncryptedUserTypes() { … }

// This is the subset of UserTypes() that have priority over other types. These
// types are synced before other user types (both for get_updates and commits).
// This mostly matters during initial sync, since priority types can become
// active before all the data for non-prio types has been downloaded (which may
// be a lot of data).
constexpr DataTypeSet HighPriorityUserTypes() { … }

// This is the subset of UserTypes() that have a *lower* priority than other
// types. These types are synced only after all other user types (both for
// get_updates and commits). This mostly matters during initial sync, since
// high-priority and regular types can become active before all the data for
// low-priority types has been downloaded (which may be a lot of data).
constexpr DataTypeSet LowPriorityUserTypes() { … }

// Returns a list of all control types.
//
// The control types are intended to contain metadata nodes that are essential
// for the normal operation of the syncer.  As such, they have the following
// special properties:
// - They are downloaded early during SyncBackend initialization.
// - They are always enabled.  Users may not disable these types.
// - Their contents are not encrypted automatically.
// - They support custom update application and conflict resolution logic.
// - All change processing occurs on the sync thread.
constexpr DataTypeSet ControlTypes() { … }

// Types that may commit data, but should never be included in a GetUpdates.
// These are never encrypted.
constexpr DataTypeSet CommitOnlyTypes() { … }

// Types for which downloaded updates are applied immediately, before all
// updates are downloaded and the Sync cycle finishes.
// For these types, DataTypeSyncBridge::MergeFullSyncData() will never be
// called (since without downloading all the data, no initial merge is
// possible).
constexpr DataTypeSet ApplyUpdatesImmediatelyTypes() { … }

// Types for which `collaboration_id` field in SyncEntity should be provided.
// These types also support `gc_directive` for collaborations to track active
// collaboratons.
constexpr DataTypeSet SharedTypes() { … }

// Types triggering a warning when the user signs out and the types have
// unsynced data. The warning offers the user to either save the data locally or
// abort sign-out, depending on the platform.
constexpr DataTypeSet TypesRequiringUnsyncedDataCheckOnSignout() { … }

// User types that can be encrypted, which is a subset of UserTypes() and a
// superset of AlwaysEncryptedUserTypes();
DataTypeSet EncryptableUserTypes();

// Determine a data type from the field number of its associated
// EntitySpecifics field.  Returns UNSPECIFIED if the field number is
// not recognized.
DataType GetDataTypeFromSpecificsFieldNumber(int field_number);

namespace internal {
// Obtain data type from field_number and add to data_types if valid.
void GetDataTypeSetFromSpecificsFieldNumberListHelper(DataTypeSet& data_types,
                                                      int field_number);
}  // namespace internal

// Build a DataTypeSet from a list of field numbers. Any unknown field numbers
// are ignored.
template <typename ContainerT>
DataTypeSet GetDataTypeSetFromSpecificsFieldNumberList(
    const ContainerT& field_numbers) { … }

// Return the field number of the EntitySpecifics field associated with
// a data type.
int GetSpecificsFieldNumberFromDataType(DataType data_type);

// Returns a string with application lifetime that represents the name of
// |data_type|.
const char* DataTypeToDebugString(DataType data_type);

// Returns a string with application lifetime that is used as the histogram
// suffix for |data_type|.
const char* DataTypeToHistogramSuffix(DataType data_type);

// Some histograms take an integer parameter that represents a data type.
// The mapping from DataType to integer is defined here. It defines a
// completely different order than the DataType enum itself. The mapping should
// match the SyncDataTypes mapping from integer to labels defined in enums.xml.
DataTypeForHistograms DataTypeHistogramValue(DataType data_type);

// Returns for every data_type a positive unique integer that is stable over
// time and thus can be used when persisting data.
int DataTypeToStableIdentifier(DataType data_type);

// Returns the comma-separated string representation of |data_types|.
std::string DataTypeSetToDebugString(DataTypeSet data_types);

// Necessary for compatibility with EXPECT_EQ and the like.
std::ostream& operator<<(std::ostream& out, DataTypeSet data_type_set);

// Returns a string corresponding to the root tag as exposed in the sync
// protocol as the root entity's ID, which makes the root entity trivially
// distinguishable from regular entities. Note that the existence of a root
// entity in the sync protocol is a legacy artifact, and modern clients ignore
// it except for bookmarks and Nigori. For this reason, the server may or may
// not return the root entity.
std::string DataTypeToProtocolRootTag(DataType data_type);

// As opposed to DataTypeToProtocolRootTag(), this returns a string that isn't
// exposed in the sync protocol, but that is still stable and thus can be used
// for local persistence. It is guaranteed to be lowercase.
const char* GetDataTypeLowerCaseRootTag(DataType data_type);

// Returns true if |data_type| is a real datatype
bool IsRealDataType(DataType data_type);

// Returns true if |data_type| is an act-once type. Act once types drop
// entities after applying them. Drops are deletes that are not synced to other
// clients.
bool IsActOnceDataType(DataType data_type);

}  // namespace syncer

#endif  // COMPONENTS_SYNC_BASE_DATA_TYPE_H_