diff options
Diffstat (limited to 'chrome/browser/sync/engine/syncapi.h')
| -rw-r--r-- | chrome/browser/sync/engine/syncapi.h | 1095 |
1 files changed, 0 insertions, 1095 deletions
diff --git a/chrome/browser/sync/engine/syncapi.h b/chrome/browser/sync/engine/syncapi.h deleted file mode 100644 index eaf9a56..0000000 --- a/chrome/browser/sync/engine/syncapi.h +++ /dev/null @@ -1,1095 +0,0 @@ -// Copyright (c) 2011 The Chromium Authors. All rights reserved. -// Use of this source code is governed by a BSD-style license that can be -// found in the LICENSE file. - -// This file defines the "sync API", an interface to the syncer -// backend that exposes (1) the core functionality of maintaining a consistent -// local snapshot of a hierarchical object set; (2) a means to transactionally -// access and modify those objects; (3) a means to control client/server -// synchronization tasks, namely: pushing local object modifications to a -// server, pulling nonlocal object modifications from a server to this client, -// and resolving conflicts that may arise between the two; and (4) an -// abstraction of some external functionality that is to be provided by the -// host environment. -// -// This interface is used as the entry point into the syncer backend -// when the backend is compiled as a library and embedded in another -// application. A goal for this interface layer is to depend on very few -// external types, so that an application can use the sync backend -// without introducing a dependency on specific types. A non-goal is to -// have binary compatibility across versions or compilers; this allows the -// interface to use C++ classes. An application wishing to use the sync API -// should ideally compile the syncer backend and this API as part of the -// application's own build, to avoid e.g. mismatches in calling convention, -// structure padding, or name mangling that could arise if there were a -// compiler mismatch. -// -// The schema of the objects in the sync domain is based on the model, which -// is essentially a hierarchy of items and folders similar to a filesystem, -// but with a few important differences. The sync API contains fields -// such as URL to easily allow the embedding application to store web -// browser bookmarks. Also, the sync API allows duplicate titles in a parent. -// Consequently, it does not support looking up an object by title -// and parent, since such a lookup is not uniquely determined. Lastly, -// unlike a filesystem model, objects in the Sync API model have a strict -// ordering within a parent; the position is manipulable by callers, and -// children of a node can be enumerated in the order of their position. - -#ifndef CHROME_BROWSER_SYNC_ENGINE_SYNCAPI_H_ -#define CHROME_BROWSER_SYNC_ENGINE_SYNCAPI_H_ -#pragma once - -#include <string> -#include <vector> - -#include "base/basictypes.h" -#include "base/callback_old.h" -#include "base/gtest_prod_util.h" -#include "base/memory/scoped_ptr.h" -#include "base/tracked.h" -#include "build/build_config.h" -#include "chrome/browser/sync/engine/configure_reason.h" -#include "chrome/browser/sync/protocol/password_specifics.pb.h" -#include "chrome/browser/sync/syncable/model_type.h" -#include "chrome/browser/sync/util/cryptographer.h" -#include "chrome/browser/sync/weak_handle.h" -#include "chrome/common/net/gaia/google_service_auth_error.h" -#include "googleurl/src/gurl.h" - -class FilePath; - -namespace base { -class DictionaryValue; -} - -namespace browser_sync { -class JsBackend; -class JsEventHandler; -class ModelSafeWorkerRegistrar; - -namespace sessions { -struct SyncSessionSnapshot; -} -} - -namespace sync_notifier { -class SyncNotifier; -} // namespace sync_notifier - -// Forward declarations of internal class types so that sync API objects -// may have opaque pointers to these types. -namespace syncable { -class BaseTransaction; -class DirectoryManager; -class Entry; -class MutableEntry; -class ReadTransaction; -class ScopedDirLookup; -class WriteTransaction; -} - -namespace sync_pb { -class AppSpecifics; -class AutofillSpecifics; -class AutofillProfileSpecifics; -class BookmarkSpecifics; -class EntitySpecifics; -class ExtensionSpecifics; -class SessionSpecifics; -class NigoriSpecifics; -class PasswordSpecifics; -class PreferenceSpecifics; -class PasswordSpecifics; -class PasswordSpecificsData; -class ThemeSpecifics; -class TypedUrlSpecifics; -} - -namespace tracked_objects { -class Location; -} // namespace tracked_objects - -namespace sync_api { - -class BaseTransaction; -class HttpPostProviderFactory; -class SyncManager; -class WriteTransaction; - -syncable::ModelTypeSet GetEncryptedTypes( - const sync_api::BaseTransaction* trans); - - -// Reasons due to which browser_sync::Cryptographer might require a passphrase. -enum PassphraseRequiredReason { - REASON_PASSPHRASE_NOT_REQUIRED = 0, // Initial value. - REASON_ENCRYPTION = 1, // The cryptographer requires a - // passphrase for its first attempt at - // encryption. Happens only during - // migration or upgrade. - REASON_DECRYPTION = 2, // The cryptographer requires a - // passphrase for its first attempt at - // decryption. - REASON_SET_PASSPHRASE_FAILED = 3, // The cryptographer requires a new - // passphrase because its attempt at - // decryption with the cached passphrase - // was unsuccessful. -}; - -// Returns the string representation of a PassphraseRequiredReason value. -std::string PassphraseRequiredReasonToString(PassphraseRequiredReason reason); - -// A UserShare encapsulates the syncable pieces that represent an authenticated -// user and their data (share). -// This encompasses all pieces required to build transaction objects on the -// syncable share. -struct UserShare { - UserShare(); - ~UserShare(); - - // The DirectoryManager itself, which is the parent of Transactions and can - // be shared across multiple threads (unlike Directory). - scoped_ptr<syncable::DirectoryManager> dir_manager; - - // The username of the sync user. - std::string name; -}; - -bool InitialSyncEndedForTypes(syncable::ModelTypeSet types, UserShare* share); - -// Contains everything needed to talk to and identify a user account. -struct SyncCredentials { - std::string email; - std::string sync_token; -}; - -// A valid BaseNode will never have an ID of zero. -static const int64 kInvalidId = 0; - -// BaseNode wraps syncable::Entry, and corresponds to a single object's state. -// This, like syncable::Entry, is intended for use on the stack. A valid -// transaction is necessary to create a BaseNode or any of its children. -// Unlike syncable::Entry, a sync API BaseNode is identified primarily by its -// int64 metahandle, which we call an ID here. -class BaseNode { - public: - // All subclasses of BaseNode must provide a way to initialize themselves by - // doing an ID lookup. Returns false on failure. An invalid or deleted - // ID will result in failure. - virtual bool InitByIdLookup(int64 id) = 0; - - // All subclasses of BaseNode must also provide a way to initialize themselves - // by doing a client tag lookup. Returns false on failure. A deleted node - // will return FALSE. - virtual bool InitByClientTagLookup(syncable::ModelType model_type, - const std::string& tag) = 0; - - // Each object is identified by a 64-bit id (internally, the syncable - // metahandle). These ids are strictly local handles. They will persist - // on this client, but the same object on a different client may have a - // different ID value. - virtual int64 GetId() const; - - // Returns the modification time of the object (in TimeTicks internal format). - int64 GetModificationTime() const; - - // Nodes are hierarchically arranged into a single-rooted tree. - // InitByRootLookup on ReadNode allows access to the root. GetParentId is - // how you find a node's parent. - int64 GetParentId() const; - - // Nodes are either folders or not. This corresponds to the IS_DIR property - // of syncable::Entry. - bool GetIsFolder() const; - - // Returns the title of the object. - // Uniqueness of the title is not enforced on siblings -- it is not an error - // for two children to share a title. - std::string GetTitle() const; - - // Returns the model type of this object. The model type is set at node - // creation time and is expected never to change. - syncable::ModelType GetModelType() const; - - // Getter specific to the BOOKMARK datatype. Returns protobuf - // data. Can only be called if GetModelType() == BOOKMARK. - const sync_pb::BookmarkSpecifics& GetBookmarkSpecifics() const; - - // Legacy, bookmark-specific getter that wraps GetBookmarkSpecifics() above. - // Returns the URL of a bookmark object. - // TODO(ncarter): Remove this datatype-specific accessor. - GURL GetURL() const; - - // Legacy, bookmark-specific getter that wraps GetBookmarkSpecifics() above. - // Fill in a vector with the byte data of this node's favicon. Assumes - // that the node is a bookmark. - // Favicons are expected to be PNG images, and though no verification is - // done on the syncapi client of this, the server may reject favicon updates - // that are invalid for whatever reason. - // TODO(ncarter): Remove this datatype-specific accessor. - void GetFaviconBytes(std::vector<unsigned char>* output) const; - - // Getter specific to the APPS datatype. Returns protobuf - // data. Can only be called if GetModelType() == APPS. - const sync_pb::AppSpecifics& GetAppSpecifics() const; - - // Getter specific to the AUTOFILL datatype. Returns protobuf - // data. Can only be called if GetModelType() == AUTOFILL. - const sync_pb::AutofillSpecifics& GetAutofillSpecifics() const; - - virtual const sync_pb::AutofillProfileSpecifics& - GetAutofillProfileSpecifics() const; - - // Getter specific to the NIGORI datatype. Returns protobuf - // data. Can only be called if GetModelType() == NIGORI. - const sync_pb::NigoriSpecifics& GetNigoriSpecifics() const; - - // Getter specific to the PASSWORD datatype. Returns protobuf - // data. Can only be called if GetModelType() == PASSWORD. - const sync_pb::PasswordSpecificsData& GetPasswordSpecifics() const; - - // Getter specific to the PREFERENCE datatype. Returns protobuf - // data. Can only be called if GetModelType() == PREFERENCE. - const sync_pb::PreferenceSpecifics& GetPreferenceSpecifics() const; - - // Getter specific to the THEME datatype. Returns protobuf - // data. Can only be called if GetModelType() == THEME. - const sync_pb::ThemeSpecifics& GetThemeSpecifics() const; - - // Getter specific to the TYPED_URLS datatype. Returns protobuf - // data. Can only be called if GetModelType() == TYPED_URLS. - const sync_pb::TypedUrlSpecifics& GetTypedUrlSpecifics() const; - - // Getter specific to the EXTENSIONS datatype. Returns protobuf - // data. Can only be called if GetModelType() == EXTENSIONS. - const sync_pb::ExtensionSpecifics& GetExtensionSpecifics() const; - - // Getter specific to the SESSIONS datatype. Returns protobuf - // data. Can only be called if GetModelType() == SESSIONS. - const sync_pb::SessionSpecifics& GetSessionSpecifics() const; - - const sync_pb::EntitySpecifics& GetEntitySpecifics() const; - - // Returns the local external ID associated with the node. - int64 GetExternalId() const; - - // Return the ID of the node immediately before this in the sibling order. - // For the first node in the ordering, return 0. - int64 GetPredecessorId() const; - - // Return the ID of the node immediately after this in the sibling order. - // For the last node in the ordering, return 0. - virtual int64 GetSuccessorId() const; - - // Return the ID of the first child of this node. If this node has no - // children, return 0. - virtual int64 GetFirstChildId() const; - - // These virtual accessors provide access to data members of derived classes. - virtual const syncable::Entry* GetEntry() const = 0; - virtual const BaseTransaction* GetTransaction() const = 0; - - // Dumps a summary of node info into a DictionaryValue and returns it. - // Transfers ownership of the DictionaryValue to the caller. - base::DictionaryValue* GetSummaryAsValue() const; - - // Dumps all node details into a DictionaryValue and returns it. - // Transfers ownership of the DictionaryValue to the caller. - base::DictionaryValue* GetDetailsAsValue() const; - - protected: - BaseNode(); - virtual ~BaseNode(); - // The server has a size limit on client tags, so we generate a fixed length - // hash locally. This also ensures that ModelTypes have unique namespaces. - static std::string GenerateSyncableHash(syncable::ModelType model_type, - const std::string& client_tag); - - // Determines whether part of the entry is encrypted, and if so attempts to - // decrypt it. Unless decryption is necessary and fails, this will always - // return |true|. If the contents are encrypted, the decrypted data will be - // stored in |unencrypted_data_|. - // This method is invoked once when the BaseNode is initialized. - bool DecryptIfNecessary(); - - // Returns the unencrypted specifics associated with |entry|. If |entry| was - // not encrypted, it directly returns |entry|'s EntitySpecifics. Otherwise, - // returns |unencrypted_data_|. - const sync_pb::EntitySpecifics& GetUnencryptedSpecifics( - const syncable::Entry* entry) const; - - // Copy |specifics| into |unencrypted_data_|. - void SetUnencryptedSpecifics(const sync_pb::EntitySpecifics& specifics); - - private: - void* operator new(size_t size); // Node is meant for stack use only. - - // A holder for the unencrypted data stored in an encrypted node. - sync_pb::EntitySpecifics unencrypted_data_; - - // Same as |unencrypted_data_|, but for legacy password encryption. - scoped_ptr<sync_pb::PasswordSpecificsData> password_data_; - - friend class SyncApiTest; - FRIEND_TEST_ALL_PREFIXES(SyncApiTest, GenerateSyncableHash); - - DISALLOW_COPY_AND_ASSIGN(BaseNode); -}; - -// WriteNode extends BaseNode to add mutation, and wraps -// syncable::MutableEntry. A WriteTransaction is needed to create a WriteNode. -class WriteNode : public BaseNode { - public: - // Create a WriteNode using the given transaction. - explicit WriteNode(WriteTransaction* transaction); - virtual ~WriteNode(); - - // A client must use one (and only one) of the following Init variants to - // populate the node. - - // BaseNode implementation. - virtual bool InitByIdLookup(int64 id); - virtual bool InitByClientTagLookup(syncable::ModelType model_type, - const std::string& tag); - - // Create a new node with the specified parent and predecessor. |model_type| - // dictates the type of the item, and controls which EntitySpecifics proto - // extension can be used with this item. Use a NULL |predecessor| - // to indicate that this is to be the first child. - // |predecessor| must be a child of |new_parent| or NULL. Returns false on - // failure. - bool InitByCreation(syncable::ModelType model_type, - const BaseNode& parent, - const BaseNode* predecessor); - - // Create nodes using this function if they're unique items that - // you want to fetch using client_tag. Note that the behavior of these - // items is slightly different than that of normal items. - // Most importantly, if it exists locally, this function will - // actually undelete it - // Client unique tagged nodes must NOT be folders. - bool InitUniqueByCreation(syncable::ModelType model_type, - const BaseNode& parent, - const std::string& client_tag); - - // Each server-created permanent node is tagged with a unique string. - // Look up the node with the particular tag. If it does not exist, - // return false. - bool InitByTagLookup(const std::string& tag); - - // These Set() functions correspond to the Get() functions of BaseNode. - void SetIsFolder(bool folder); - void SetTitle(const std::wstring& title); - - // External ID is a client-only field, so setting it doesn't cause the item to - // be synced again. - void SetExternalId(int64 external_id); - - // Remove this node and its children. - void Remove(); - - // Set a new parent and position. Position is specified by |predecessor|; if - // it is NULL, the node is moved to the first position. |predecessor| must - // be a child of |new_parent| or NULL. Returns false on failure.. - bool SetPosition(const BaseNode& new_parent, const BaseNode* predecessor); - - // Set the bookmark specifics (url and favicon). - // Should only be called if GetModelType() == BOOKMARK. - void SetBookmarkSpecifics(const sync_pb::BookmarkSpecifics& specifics); - - // Legacy, bookmark-specific setters that wrap SetBookmarkSpecifics() above. - // Should only be called if GetModelType() == BOOKMARK. - // TODO(ncarter): Remove these two datatype-specific accessors. - void SetURL(const GURL& url); - void SetFaviconBytes(const std::vector<unsigned char>& bytes); - - // Generic set specifics method. Will extract the model type from |specifics|. - void SetEntitySpecifics(const sync_pb::EntitySpecifics& specifics); - - // Resets the EntitySpecifics for this node based on the unencrypted data. - // Will encrypt if necessary. - void ResetFromSpecifics(); - - // TODO(sync): Remove the setters below when the corresponding data - // types are ported to the new sync service API. - - // Set the app specifics (id, update url, enabled state, etc). - // Should only be called if GetModelType() == APPS. - void SetAppSpecifics(const sync_pb::AppSpecifics& specifics); - - // Set the autofill specifics (name and value). - // Should only be called if GetModelType() == AUTOFILL. - void SetAutofillSpecifics(const sync_pb::AutofillSpecifics& specifics); - - void SetAutofillProfileSpecifics( - const sync_pb::AutofillProfileSpecifics& specifics); - - // Set the nigori specifics. - // Should only be called if GetModelType() == NIGORI. - void SetNigoriSpecifics(const sync_pb::NigoriSpecifics& specifics); - - // Set the password specifics. - // Should only be called if GetModelType() == PASSWORD. - void SetPasswordSpecifics(const sync_pb::PasswordSpecificsData& specifics); - - // Set the theme specifics (name and value). - // Should only be called if GetModelType() == THEME. - void SetThemeSpecifics(const sync_pb::ThemeSpecifics& specifics); - - // Set the typed_url specifics (url, title, typed_count, etc). - // Should only be called if GetModelType() == TYPED_URLS. - void SetTypedUrlSpecifics(const sync_pb::TypedUrlSpecifics& specifics); - - // Set the extension specifics (id, update url, enabled state, etc). - // Should only be called if GetModelType() == EXTENSIONS. - void SetExtensionSpecifics(const sync_pb::ExtensionSpecifics& specifics); - - // Set the session specifics (windows, tabs, navigations etc.). - // Should only be called if GetModelType() == SESSIONS. - void SetSessionSpecifics(const sync_pb::SessionSpecifics& specifics); - - // Stores |new_specifics| into |entry|, encrypting if necessary. - // Returns false if an error encrypting occurred (does not modify |entry|). - // Note: gracefully handles new_specifics aliasing with entry->Get(SPECIFICS). - static bool UpdateEntryWithEncryption( - browser_sync::Cryptographer* cryptographer, - const sync_pb::EntitySpecifics& new_specifics, - syncable::MutableEntry* entry); - - // Implementation of BaseNode's abstract virtual accessors. - virtual const syncable::Entry* GetEntry() const; - - virtual const BaseTransaction* GetTransaction() const; - - private: - void* operator new(size_t size); // Node is meant for stack use only. - - // Helper to set model type. This will clear any specifics data. - void PutModelType(syncable::ModelType model_type); - - // Helper to set the previous node. - void PutPredecessor(const BaseNode* predecessor); - - // Sets IS_UNSYNCED and SYNCING to ensure this entry is considered in an - // upcoming commit pass. - void MarkForSyncing(); - - // The underlying syncable object which this class wraps. - syncable::MutableEntry* entry_; - - // The sync API transaction that is the parent of this node. - WriteTransaction* transaction_; - - DISALLOW_COPY_AND_ASSIGN(WriteNode); -}; - -// ReadNode wraps a syncable::Entry to provide the functionality of a -// read-only BaseNode. -class ReadNode : public BaseNode { - public: - // Create an unpopulated ReadNode on the given transaction. Call some flavor - // of Init to populate the ReadNode with a database entry. - explicit ReadNode(const BaseTransaction* transaction); - virtual ~ReadNode(); - - // A client must use one (and only one) of the following Init variants to - // populate the node. - - // BaseNode implementation. - virtual bool InitByIdLookup(int64 id); - virtual bool InitByClientTagLookup(syncable::ModelType model_type, - const std::string& tag); - - // There is always a root node, so this can't fail. The root node is - // never mutable, so root lookup is only possible on a ReadNode. - void InitByRootLookup(); - - // Each server-created permanent node is tagged with a unique string. - // Look up the node with the particular tag. If it does not exist, - // return false. - bool InitByTagLookup(const std::string& tag); - - // Implementation of BaseNode's abstract virtual accessors. - virtual const syncable::Entry* GetEntry() const; - virtual const BaseTransaction* GetTransaction() const; - - protected: - ReadNode(); - - private: - void* operator new(size_t size); // Node is meant for stack use only. - - // The underlying syncable object which this class wraps. - syncable::Entry* entry_; - - // The sync API transaction that is the parent of this node. - const BaseTransaction* transaction_; - - DISALLOW_COPY_AND_ASSIGN(ReadNode); -}; - -// Sync API's BaseTransaction, ReadTransaction, and WriteTransaction allow for -// batching of several read and/or write operations. The read and write -// operations are performed by creating ReadNode and WriteNode instances using -// the transaction. These transaction classes wrap identically named classes in -// syncable, and are used in a similar way. Unlike syncable::BaseTransaction, -// whose construction requires an explicit syncable::ScopedDirLookup, a sync -// API BaseTransaction creates its own ScopedDirLookup implicitly. -class BaseTransaction { - public: - // Provide access to the underlying syncable.h objects from BaseNode. - virtual syncable::BaseTransaction* GetWrappedTrans() const = 0; - const syncable::ScopedDirLookup& GetLookup() const { return *lookup_; } - browser_sync::Cryptographer* GetCryptographer() const { - return cryptographer_; - } - - protected: - // The ScopedDirLookup is created in the constructor and destroyed - // in the destructor. Creation of the ScopedDirLookup is not expected - // to fail. - explicit BaseTransaction(UserShare* share); - virtual ~BaseTransaction(); - - BaseTransaction() { lookup_= NULL; } - - private: - // A syncable ScopedDirLookup, which is the parent of syncable transactions. - syncable::ScopedDirLookup* lookup_; - - browser_sync::Cryptographer* cryptographer_; - - DISALLOW_COPY_AND_ASSIGN(BaseTransaction); -}; - -// TODO(akalin): Make ReadTransaction/WriteTransaction take a Location -// parameter. - -// Sync API's ReadTransaction is a read-only BaseTransaction. It wraps -// a syncable::ReadTransaction. -class ReadTransaction : public BaseTransaction { - public: - // Start a new read-only transaction on the specified repository. - ReadTransaction(const tracked_objects::Location& from_here, - UserShare* share); - - // Resume the middle of a transaction. Will not close transaction. - ReadTransaction(UserShare* share, syncable::BaseTransaction* trans); - - virtual ~ReadTransaction(); - - // BaseTransaction override. - virtual syncable::BaseTransaction* GetWrappedTrans() const; - private: - void* operator new(size_t size); // Transaction is meant for stack use only. - - // The underlying syncable object which this class wraps. - syncable::BaseTransaction* transaction_; - bool close_transaction_; - - DISALLOW_COPY_AND_ASSIGN(ReadTransaction); -}; - -// Sync API's WriteTransaction is a read/write BaseTransaction. It wraps -// a syncable::WriteTransaction. -// -// NOTE: Only a single model type can be mutated for a given -// WriteTransaction. -class WriteTransaction : public BaseTransaction { - public: - // Start a new read/write transaction. - WriteTransaction(const tracked_objects::Location& from_here, - UserShare* share); - virtual ~WriteTransaction(); - - // Provide access to the syncable.h transaction from the API WriteNode. - virtual syncable::BaseTransaction* GetWrappedTrans() const; - syncable::WriteTransaction* GetWrappedWriteTrans() { return transaction_; } - - protected: - WriteTransaction() {} - - void SetTransaction(syncable::WriteTransaction* trans) { - transaction_ = trans; - } - - private: - void* operator new(size_t size); // Transaction is meant for stack use only. - - // The underlying syncable object which this class wraps. - syncable::WriteTransaction* transaction_; - - DISALLOW_COPY_AND_ASSIGN(WriteTransaction); -}; - -// SyncManager encapsulates syncable::DirectoryManager and serves as the parent -// of all other objects in the sync API. SyncManager is thread-safe. If -// multiple threads interact with the same local sync repository (i.e. the -// same sqlite database), they should share a single SyncManager instance. The -// caller should typically create one SyncManager for the lifetime of a user -// session. -class SyncManager { - public: - // SyncInternal contains the implementation of SyncManager, while abstracting - // internal types from clients of the interface. - class SyncInternal; - - // TODO(zea): One day get passwords playing nicely with the rest of encryption - // and get rid of this. - class ExtraPasswordChangeRecordData { - public: - ExtraPasswordChangeRecordData(); - explicit ExtraPasswordChangeRecordData( - const sync_pb::PasswordSpecificsData& data); - virtual ~ExtraPasswordChangeRecordData(); - - // Transfers ownership of the DictionaryValue to the caller. - virtual base::DictionaryValue* ToValue() const; - - const sync_pb::PasswordSpecificsData& unencrypted() const; - private: - sync_pb::PasswordSpecificsData unencrypted_; - }; - - // ChangeRecord indicates a single item that changed as a result of a sync - // operation. This gives the sync id of the node that changed, and the type - // of change. To get the actual property values after an ADD or UPDATE, the - // client should get the node with InitByIdLookup(), using the provided id. - struct ChangeRecord { - enum Action { - ACTION_ADD, - ACTION_DELETE, - ACTION_UPDATE, - }; - ChangeRecord(); - ~ChangeRecord(); - - // Transfers ownership of the DictionaryValue to the caller. - base::DictionaryValue* ToValue(const BaseTransaction* trans) const; - - int64 id; - Action action; - sync_pb::EntitySpecifics specifics; - linked_ptr<ExtraPasswordChangeRecordData> extra; - }; - - // Status encapsulates detailed state about the internals of the SyncManager. - struct Status { - // Summary is a distilled set of important information that the end-user may - // wish to be informed about (through UI, for example). Note that if a - // summary state requires user interaction (such as auth failures), more - // detailed information may be contained in additional status fields. - enum Summary { - // The internal instance is in an unrecognizable state. This should not - // happen. - INVALID = 0, - // Can't connect to server, but there are no pending changes in - // our local cache. - OFFLINE, - // Can't connect to server, and there are pending changes in our - // local cache. - OFFLINE_UNSYNCED, - // Connected and syncing. - SYNCING, - // Connected, no pending changes. - READY, - // Internal sync error. - CONFLICT, - // Can't connect to server, and we haven't completed the initial - // sync yet. So there's nothing we can do but wait for the server. - OFFLINE_UNUSABLE, - - SUMMARY_STATUS_COUNT, - }; - - Status(); - ~Status(); - - Summary summary; - bool authenticated; // Successfully authenticated via GAIA. - bool server_up; // True if we have received at least one good - // reply from the server. - bool server_reachable; // True if we received any reply from the server. - bool server_broken; // True of the syncer is stopped because of server - // issues. - bool notifications_enabled; // True only if subscribed for notifications. - - // Notifications counters updated by the actions in synapi. - int notifications_received; - int notifiable_commits; - - // The max number of consecutive errors from any component. - int max_consecutive_errors; - - int unsynced_count; - - int conflicting_count; - bool syncing; - // True after a client has done a first sync. - bool initial_sync_ended; - // True if any syncer is stuck. - bool syncer_stuck; - - // Total updates available. If zero, nothing left to download. - int64 updates_available; - // Total updates received by the syncer since browser start. - int updates_received; - - // Of updates_received, how many were tombstones. - int tombstone_updates_received; - bool disk_full; - - // Total number of overwrites due to conflict resolver since browser start. - int num_local_overwrites_total; - int num_server_overwrites_total; - - // Count of empty and non empty getupdates; - int nonempty_get_updates; - int empty_get_updates; - - // Count of useless and useful syncs we perform. - int useless_sync_cycles; - int useful_sync_cycles; - - // Encryption related. - syncable::ModelTypeSet encrypted_types; - bool cryptographer_ready; - bool crypto_has_pending_keys; - }; - - // An interface the embedding application implements to receive notifications - // from the SyncManager. Register an observer via SyncManager::AddObserver. - // This observer is an event driven model as the events may be raised from - // different internal threads, and simply providing an "OnStatusChanged" type - // notification complicates things such as trying to determine "what changed", - // if different members of the Status object are modified from different - // threads. This way, the event is explicit, and it is safe for the Observer - // to dispatch to a native thread or synchronize accordingly. - class Observer { - public: - // Notify the observer that changes have been applied to the sync model. - // - // This will be invoked on the same thread as on which ApplyChanges was - // called. |changes| is an array of size |change_count|, and contains the - // ID of each individual item that was changed. |changes| exists only for - // the duration of the call. If items of multiple data types change at - // the same time, this method is invoked once per data type and |changes| - // is restricted to items of the ModelType indicated by |model_type|. - // Because the observer is passed a |trans|, the observer can assume a - // read lock on the sync model that will be released after the function - // returns. - // - // The SyncManager constructs |changes| in the following guaranteed order: - // - // 1. Deletions, from leaves up to parents. - // 2. Updates to existing items with synced parents & predecessors. - // 3. New items with synced parents & predecessors. - // 4. Items with parents & predecessors in |changes|. - // 5. Repeat #4 until all items are in |changes|. - // - // Thus, an implementation of OnChangesApplied should be able to - // process the change records in the order without having to worry about - // forward dependencies. But since deletions come before reparent - // operations, a delete may temporarily orphan a node that is - // updated later in the list. - virtual void OnChangesApplied(syncable::ModelType model_type, - const BaseTransaction* trans, - const ChangeRecord* changes, - int change_count) = 0; - - // OnChangesComplete gets called when the TransactionComplete event is - // posted (after OnChangesApplied finishes), after the transaction lock - // and the change channel mutex are released. - // - // The purpose of this function is to support processors that require - // split-transactions changes. For example, if a model processor wants to - // perform blocking I/O due to a change, it should calculate the changes - // while holding the transaction lock (from within OnChangesApplied), buffer - // those changes, let the transaction fall out of scope, and then commit - // those changes from within OnChangesComplete (postponing the blocking - // I/O to when it no longer holds any lock). - virtual void OnChangesComplete(syncable::ModelType model_type) = 0; - - // A round-trip sync-cycle took place and the syncer has resolved any - // conflicts that may have arisen. - virtual void OnSyncCycleCompleted( - const browser_sync::sessions::SyncSessionSnapshot* snapshot) = 0; - - // Called when user interaction may be required due to an auth problem. - virtual void OnAuthError(const GoogleServiceAuthError& auth_error) = 0; - - // Called when a new auth token is provided by the sync server. - virtual void OnUpdatedToken(const std::string& token) = 0; - - // Called when user interaction is required to obtain a valid passphrase. - // - If the passphrase is required for encryption, |reason| will be - // REASON_ENCRYPTION. - // - If the passphrase is required for the decryption of data that has - // already been encrypted, |reason| will be REASON_DECRYPTION. - // - If the passphrase is required because decryption failed, and a new - // passphrase is required, |reason| will be REASON_SET_PASSPHRASE_FAILED. - virtual void OnPassphraseRequired(PassphraseRequiredReason reason) = 0; - - // Called when the passphrase provided by the user has been accepted and is - // now used to encrypt sync data. |bootstrap_token| is an opaque base64 - // encoded representation of the key generated by the accepted passphrase, - // and is provided to the observer for persistence purposes and use in a - // future initialization of sync (e.g. after restart). - virtual void OnPassphraseAccepted(const std::string& bootstrap_token) = 0; - - // Called when initialization is complete to the point that SyncManager can - // process changes. This does not necessarily mean authentication succeeded - // or that the SyncManager is online. - // IMPORTANT: Creating any type of transaction before receiving this - // notification is illegal! - // WARNING: Calling methods on the SyncManager before receiving this - // message, unless otherwise specified, produces undefined behavior. - // - // |js_backend| is what about:sync interacts with. It can emit - // the following events: - - /** - * @param {{ enabled: boolean }} details A dictionary containing: - * - enabled: whether or not notifications are enabled. - */ - // function onNotificationStateChange(details); - - /** - * @param {{ changedTypes: Array.<string> }} details A dictionary - * containing: - * - changedTypes: a list of types (as strings) for which there - are new updates. - */ - // function onIncomingNotification(details); - - // Also, it responds to the following messages (all other messages - // are ignored): - - /** - * Gets the current notification state. - * - * @param {function(boolean)} callback Called with whether or not - * notifications are enabled. - */ - // function getNotificationState(callback); - - /** - * Gets details about the root node. - * - * @param {function(!Object)} callback Called with details about the - * root node. - */ - // TODO(akalin): Change this to getRootNodeId or eliminate it - // entirely. - // function getRootNodeDetails(callback); - - /** - * Gets summary information for a list of ids. - * - * @param {Array.<string>} idList List of 64-bit ids in decimal - * string form. - * @param {Array.<{id: string, title: string, isFolder: boolean}>} - * callback Called with summaries for the nodes in idList that - * exist. - */ - // function getNodeSummariesById(idList, callback); - - /** - * Gets detailed information for a list of ids. - * - * @param {Array.<string>} idList List of 64-bit ids in decimal - * string form. - * @param {Array.<!Object>} callback Called with detailed - * information for the nodes in idList that exist. - */ - // function getNodeDetailsById(idList, callback); - - /** - * Gets child ids for a given id. - * - * @param {string} id 64-bit id in decimal string form of the parent - * node. - * @param {Array.<string>} callback Called with the (possibly empty) - * list of child ids. - */ - // function getChildNodeIds(id); - - virtual void OnInitializationComplete( - const browser_sync::WeakHandle<browser_sync::JsBackend>& - js_backend) = 0; - - // We are no longer permitted to communicate with the server. Sync should - // be disabled and state cleaned up at once. This can happen for a number - // of reasons, e.g. swapping from a test instance to production, or a - // global stop syncing operation has wiped the store. - virtual void OnStopSyncingPermanently() = 0; - - // After a request to clear server data, these callbacks are invoked to - // indicate success or failure. - virtual void OnClearServerDataSucceeded() = 0; - virtual void OnClearServerDataFailed() = 0; - - // Called after we finish encrypting all appropriate datatypes. - virtual void OnEncryptionComplete( - const syncable::ModelTypeSet& encrypted_types) = 0; - - protected: - virtual ~Observer(); - }; - - typedef Callback0::Type ModeChangeCallback; - - // Create an uninitialized SyncManager. Callers must Init() before using. - explicit SyncManager(const std::string& name); - virtual ~SyncManager(); - - // Initialize the sync manager. |database_location| specifies the path of - // the directory in which to locate a sqlite repository storing the syncer - // backend state. Initialization will open the database, or create it if it - // does not already exist. Returns false on failure. - // |event_handler| is the JsEventHandler used to propagate events to - // chrome://sync-internals. |event_handler| may be uninitialized. - // |sync_server_and_path| and |sync_server_port| represent the Chrome sync - // server to use, and |use_ssl| specifies whether to communicate securely; - // the default is false. - // |post_factory| will be owned internally and used to create - // instances of an HttpPostProvider. - // |model_safe_worker| ownership is given to the SyncManager. - // |user_agent| is a 7-bit ASCII string suitable for use as the User-Agent - // HTTP header. Used internally when collecting stats to classify clients. - // |sync_notifier| is owned and used to listen for notifications. - bool Init(const FilePath& database_location, - const browser_sync::WeakHandle<browser_sync::JsEventHandler>& - event_handler, - const std::string& sync_server_and_path, - int sync_server_port, - bool use_ssl, - HttpPostProviderFactory* post_factory, - browser_sync::ModelSafeWorkerRegistrar* registrar, - const std::string& user_agent, - const SyncCredentials& credentials, - sync_notifier::SyncNotifier* sync_notifier, - const std::string& restored_key_for_bootstrapping, - bool setup_for_test_mode); - - // Returns the username last used for a successful authentication. - // Returns empty if there is no such username. - const std::string& GetAuthenticatedUsername(); - - // Check if the database has been populated with a full "initial" download of - // sync items for each data type currently present in the routing info. - // Prerequisite for calling this is that OnInitializationComplete has been - // called. - bool InitialSyncEndedForAllEnabledTypes(); - - // Update tokens that we're using in Sync. Email must stay the same. - void UpdateCredentials(const SyncCredentials& credentials); - - // Called when the user disables or enables a sync type. - void UpdateEnabledTypes(); - - // Put the syncer in normal mode ready to perform nudges and polls. - void StartSyncingNormally(); - - // Attempt to set the passphrase. If the passphrase is valid, - // OnPassphraseAccepted will be fired to notify the ProfileSyncService and the - // syncer will be nudged so that any update that was waiting for this - // passphrase gets applied as soon as possible. - // If the passphrase in invalid, OnPassphraseRequired will be fired. - // Calling this metdod again is the appropriate course of action to "retry" - // with a new passphrase. - // |is_explicit| is true if the call is in response to the user explicitly - // setting a passphrase as opposed to implicitly (from the users' perspective) - // using their Google Account password. An implicit SetPassphrase will *not* - // *not* override an explicit passphrase set previously. - void SetPassphrase(const std::string& passphrase, bool is_explicit); - - // Set the datatypes we want to encrypt and encrypt any nodes as necessary. - // Note: |encrypted_types| will be unioned with the current set of encrypted - // types, as we do not currently support decrypting datatypes. - void EncryptDataTypes(const syncable::ModelTypeSet& encrypted_types); - - // Puts the SyncScheduler into a mode where no normal nudge or poll traffic - // will occur, but calls to RequestConfig will be supported. If |callback| - // is provided, it will be invoked (from the internal SyncScheduler) when - // the thread has changed to configuration mode. - void StartConfigurationMode(ModeChangeCallback* callback); - - // Switches the mode of operation to CONFIGURATION_MODE and - // schedules a config task to fetch updates for |types|. - void RequestConfig(const syncable::ModelTypeBitSet& types, - sync_api::ConfigureReason reason); - - void RequestCleanupDisabledTypes(); - - // Request a clearing of all data on the server - void RequestClearServerData(); - - // Adds a listener to be notified of sync events. - // NOTE: It is OK (in fact, it's probably a good idea) to call this before - // having received OnInitializationCompleted. - void AddObserver(Observer* observer); - - // Remove the given observer. Make sure to call this if the - // Observer is being destroyed so the SyncManager doesn't - // potentially dereference garbage. - void RemoveObserver(Observer* observer); - - // Status-related getters. Typically GetStatusSummary will suffice, but - // GetDetailedSyncStatus can be useful for gathering debug-level details of - // the internals of the sync engine. - Status::Summary GetStatusSummary() const; - Status GetDetailedStatus() const; - - // Whether or not the Nigori node is encrypted using an explicit passphrase. - bool IsUsingExplicitPassphrase(); - - // Get the internal implementation for use by BaseTransaction, etc. - SyncInternal* GetImpl() const; - - // Call periodically from a database-safe thread to persist recent changes - // to the syncapi model. - void SaveChanges(); - - void RequestEarlyExit(); - - // Issue a final SaveChanges, close sqlite handles, and stop running threads. - // Must be called from the same thread that called Init(). - void Shutdown(); - - UserShare* GetUserShare() const; - - // Inform the cryptographer of the most recent passphrase and set of encrypted - // types (from nigori node), then ensure all data that needs encryption is - // encrypted with the appropriate passphrase. - // Note: opens a transaction and can trigger ON_PASSPHRASE_REQUIRED, so must - // only be called after syncapi has been initialized. - void RefreshEncryption(); - - syncable::ModelTypeSet GetEncryptedDataTypes() const; - - // Uses a read-only transaction to determine if the directory being synced has - // any remaining unsynced items. - bool HasUnsyncedItems() const; - - // Logs the list of unsynced meta handles. - void LogUnsyncedItems(int level) const; - - // Functions used for testing. - - void TriggerOnNotificationStateChangeForTest( - bool notifications_enabled); - - void TriggerOnIncomingNotificationForTest( - const syncable::ModelTypeBitSet& model_types); - - private: - // An opaque pointer to the nested private class. - SyncInternal* data_; - - DISALLOW_COPY_AND_ASSIGN(SyncManager); -}; - -} // namespace sync_api - -#endif // CHROME_BROWSER_SYNC_ENGINE_SYNCAPI_H_ |