sync/internal_api/public/base_node.h

   1 // Copyright 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 #ifndef SYNC_INTERNAL_API_PUBLIC_BASE_NODE_H_
   6 #define SYNC_INTERNAL_API_PUBLIC_BASE_NODE_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/basictypes.h"
  12 #include "base/gtest_prod_util.h"
  13 #include "base/memory/scoped_ptr.h"
  14 #include "base/time/time.h"
  15 #include "sync/api/attachments/attachment.h"
  16 #include "sync/base/sync_export.h"
  17 #include "sync/internal_api/public/base/model_type.h"
  18 #include "sync/protocol/sync.pb.h"
  19 #include "url/gurl.h"
  20
  21 // Forward declarations of internal class types so that sync API objects
  22 // may have opaque pointers to these types.
  23 namespace base {
  24 class DictionaryValue;
  25 }
  26
  27 namespace sync_pb {
  28 class AppSpecifics;
  29 class AutofillSpecifics;
  30 class AutofillProfileSpecifics;
  31 class BookmarkSpecifics;
  32 class EntitySpecifics;
  33 class ExtensionSpecifics;
  34 class SessionSpecifics;
  35 class NigoriSpecifics;
  36 class PreferenceSpecifics;
  37 class PasswordSpecificsData;
  38 class ThemeSpecifics;
  39 class TypedUrlSpecifics;
  40 }
  41
  42 namespace syncer {
  43
  44 class BaseTransaction;
  45
  46 namespace syncable {
  47 class BaseTransaction;
  48 class Entry;
  49 }
  50
  51 // A valid BaseNode will never have an ID of zero.
  52 static const int64 kInvalidId = 0;
  53
  54 // BaseNode wraps syncable::Entry, and corresponds to a single object's state.
  55 // This, like syncable::Entry, is intended for use on the stack.  A valid
  56 // transaction is necessary to create a BaseNode or any of its children.
  57 // Unlike syncable::Entry, a sync API BaseNode is identified primarily by its
  58 // int64 metahandle, which we call an ID here.
  59 class SYNC_EXPORT BaseNode {
  60  public:
  61   // Enumerates the possible outcomes of trying to initialize a sync node.
  62   enum InitByLookupResult {
  63     INIT_OK,
  64     // Could not find an entry matching the lookup criteria.
  65     INIT_FAILED_ENTRY_NOT_GOOD,
  66     // Found an entry, but it is already deleted.
  67     INIT_FAILED_ENTRY_IS_DEL,
  68     // Found an entry, but was unable to decrypt.
  69     INIT_FAILED_DECRYPT_IF_NECESSARY,
  70     // A precondition was not met for calling init, such as legal input
  71     // arguments.
  72     INIT_FAILED_PRECONDITION,
  73   };
  74
  75   // All subclasses of BaseNode must provide a way to initialize themselves by
  76   // doing an ID lookup.  Returns false on failure.  An invalid or deleted
  77   // ID will result in failure.
  78   virtual InitByLookupResult InitByIdLookup(int64 id) = 0;
  79
  80   // All subclasses of BaseNode must also provide a way to initialize themselves
  81   // by doing a client tag lookup. Returns false on failure. A deleted node
  82   // will return FALSE.
  83   virtual InitByLookupResult InitByClientTagLookup(
  84       ModelType model_type,
  85       const std::string& tag) = 0;
  86
  87   // Each object is identified by a 64-bit id (internally, the syncable
  88   // metahandle).  These ids are strictly local handles.  They will persist
  89   // on this client, but the same object on a different client may have a
  90   // different ID value.
  91   virtual int64 GetId() const;
  92
  93   // Returns the modification time of the object.
  94   base::Time GetModificationTime() const;
  95
  96   // Nodes are hierarchically arranged into a single-rooted tree.
  97   // InitByRootLookup on ReadNode allows access to the root. GetParentId is
  98   // how you find a node's parent.
  99   int64 GetParentId() const;
 100
 101   // Nodes are either folders or not.  This corresponds to the IS_DIR property
 102   // of syncable::Entry.
 103   bool GetIsFolder() const;
 104
 105   // Returns the title of the object.
 106   // Uniqueness of the title is not enforced on siblings -- it is not an error
 107   // for two children to share a title.
 108   std::string GetTitle() const;
 109
 110   // Returns the model type of this object.  The model type is set at node
 111   // creation time and is expected never to change.
 112   ModelType GetModelType() const;
 113
 114   // Getter specific to the BOOKMARK datatype.  Returns protobuf
 115   // data.  Can only be called if GetModelType() == BOOKMARK.
 116   const sync_pb::BookmarkSpecifics& GetBookmarkSpecifics() const;
 117
 118   // Getter specific to the NIGORI datatype.  Returns protobuf
 119   // data.  Can only be called if GetModelType() == NIGORI.
 120   const sync_pb::NigoriSpecifics& GetNigoriSpecifics() const;
 121
 122   // Getter specific to the PASSWORD datatype.  Returns protobuf
 123   // data.  Can only be called if GetModelType() == PASSWORD.
 124   const sync_pb::PasswordSpecificsData& GetPasswordSpecifics() const;
 125
 126   // Getter specific to the TYPED_URLS datatype.  Returns protobuf
 127   // data.  Can only be called if GetModelType() == TYPED_URLS.
 128   const sync_pb::TypedUrlSpecifics& GetTypedUrlSpecifics() const;
 129
 130   // Getter specific to the EXPERIMENTS datatype.  Returns protobuf
 131   // data.  Can only be called if GetModelType() == EXPERIMENTS.
 132   const sync_pb::ExperimentsSpecifics& GetExperimentsSpecifics() const;
 133
 134   const sync_pb::EntitySpecifics& GetEntitySpecifics() const;
 135
 136   // Returns the local external ID associated with the node.
 137   int64 GetExternalId() const;
 138
 139   // Returns true iff this node has children.
 140   bool HasChildren() const;
 141
 142   // Return the ID of the node immediately before this in the sibling order.
 143   // For the first node in the ordering, return 0.
 144   int64 GetPredecessorId() const;
 145
 146   // Return the ID of the node immediately after this in the sibling order.
 147   // For the last node in the ordering, return 0.
 148   int64 GetSuccessorId() const;
 149
 150   // Return the ID of the first child of this node.  If this node has no
 151   // children, return 0.
 152   int64 GetFirstChildId() const;
 153
 154   // Returns the IDs of the children of this node.
 155   // If this type supports user-defined positions the returned IDs will be in
 156   // the correct order.
 157   void GetChildIds(std::vector<int64>* result) const;
 158
 159   // Returns the total number of nodes including and beneath this node.
 160   // Recursively iterates through all children.
 161   int GetTotalNodeCount() const;
 162
 163   // Returns this item's position within its parent.
 164   // Do not call this function on items that do not support positioning
 165   // (ie. non-bookmarks).
 166   int GetPositionIndex() const;
 167
 168   // Returns this item's attachment ids.
 169   const syncer::AttachmentIdList GetAttachmentIds() const;
 170
 171   // These virtual accessors provide access to data members of derived classes.
 172   virtual const syncable::Entry* GetEntry() const = 0;
 173   virtual const BaseTransaction* GetTransaction() const = 0;
 174
 175   // Returns a base::DictionaryValue serialization of this node.
 176   base::DictionaryValue* ToValue() const;
 177
 178  protected:
 179   BaseNode();
 180   virtual ~BaseNode();
 181
 182   // Determines whether part of the entry is encrypted, and if so attempts to
 183   // decrypt it. Unless decryption is necessary and fails, this will always
 184   // return |true|. If the contents are encrypted, the decrypted data will be
 185   // stored in |unencrypted_data_|.
 186   // This method is invoked once when the BaseNode is initialized.
 187   bool DecryptIfNecessary();
 188
 189   // Returns the unencrypted specifics associated with |entry|. If |entry| was
 190   // not encrypted, it directly returns |entry|'s EntitySpecifics. Otherwise,
 191   // returns |unencrypted_data_|.
 192   const sync_pb::EntitySpecifics& GetUnencryptedSpecifics(
 193       const syncable::Entry* entry) const;
 194
 195   // Copy |specifics| into |unencrypted_data_|.
 196   void SetUnencryptedSpecifics(const sync_pb::EntitySpecifics& specifics);
 197
 198  private:
 199   // Have to friend the test class as well to allow member functions to access
 200   // protected/private BaseNode methods.
 201   friend class SyncManagerTest;
 202   FRIEND_TEST_ALL_PREFIXES(SyncApiTest, GenerateSyncableHash);
 203   FRIEND_TEST_ALL_PREFIXES(SyncManagerTest, UpdateEntryWithEncryption);
 204   FRIEND_TEST_ALL_PREFIXES(SyncManagerTest,
 205                            UpdatePasswordSetEntitySpecificsNoChange);
 206   FRIEND_TEST_ALL_PREFIXES(SyncManagerTest, UpdatePasswordSetPasswordSpecifics);
 207   FRIEND_TEST_ALL_PREFIXES(SyncManagerTest, UpdatePasswordNewPassphrase);
 208   FRIEND_TEST_ALL_PREFIXES(SyncManagerTest, UpdatePasswordReencryptEverything);
 209   FRIEND_TEST_ALL_PREFIXES(SyncManagerTest, SetBookmarkTitle);
 210   FRIEND_TEST_ALL_PREFIXES(SyncManagerTest, SetBookmarkTitleWithEncryption);
 211   FRIEND_TEST_ALL_PREFIXES(SyncManagerTest, SetNonBookmarkTitle);
 212   FRIEND_TEST_ALL_PREFIXES(SyncManagerTest, SetNonBookmarkTitleWithEncryption);
 213   FRIEND_TEST_ALL_PREFIXES(SyncManagerTest, SetPreviouslyEncryptedSpecifics);
 214   FRIEND_TEST_ALL_PREFIXES(SyncManagerTest, IncrementTransactionVersion);
 215
 216   void* operator new(size_t size);  // Node is meant for stack use only.
 217
 218   // A holder for the unencrypted data stored in an encrypted node.
 219   sync_pb::EntitySpecifics unencrypted_data_;
 220
 221   // Same as |unencrypted_data_|, but for legacy password encryption.
 222   scoped_ptr<sync_pb::PasswordSpecificsData> password_data_;
 223
 224   DISALLOW_COPY_AND_ASSIGN(BaseNode);
 225 };
 226
 227 }  // namespace syncer
 228
 229 #endif  // SYNC_INTERNAL_API_PUBLIC_BASE_NODE_H_