Upstream version 7.36.149.0

[platform/framework/web/crosswalk.git] / src / sync / api / attachments / attachment_store.h

diff --git a/src/sync/api/attachments/attachment_store.h b/src/sync/api/attachments/attachment_store.h
index d4e951e..d86cd1b 100644 (file)
--- a/src/sync/api/attachments/attachment_store.h
+++ b/src/sync/api/attachments/attachment_store.h
@@ -8,62 +8,75 @@
 #include "base/callback.h"
 #include "base/memory/ref_counted.h"
 #include "base/memory/scoped_ptr.h"
+#include "sync/api/attachments/attachment.h"
+#include "sync/api/attachments/attachment_id.h"
 #include "sync/base/sync_export.h"
 
 namespace base {
 class RefCountedMemory;
 }  // namespace base
 
-namespace sync_pb {
-class AttachmentId;
-}  // namespace sync_pb
-
 namespace syncer {
 
 class Attachment;
+class AttachmentId;
 
 // A place to locally store and access Attachments.
+//
+// Destroying this object does not necessarily cancel outstanding async
+// operations. If you need cancel like semantics, use WeakPtr in the callbacks.
 class SYNC_EXPORT AttachmentStore {
  public:
   AttachmentStore();
   virtual ~AttachmentStore();
 
   // TODO(maniscalco): Consider udpating Read and Write methods to support
-  // resumable transfers.
+  // resumable transfers (bug 353292).
 
   enum Result {
-    SUCCESS,            // No error.
-    NOT_FOUND,          // Attachment was not found or does not exist.
-    UNSPECIFIED_ERROR,  // An unspecified error occurred.
+    SUCCESS,            // No error, all completed successfully.
+    UNSPECIFIED_ERROR,  // An unspecified error occurred for one or more items.
   };
 
-  typedef base::Callback<void(const Result&, scoped_ptr<Attachment>)>
+  typedef base::Callback<void(const Result&, scoped_ptr<AttachmentMap>)>
       ReadCallback;
   typedef base::Callback<void(const Result&)> WriteCallback;
   typedef base::Callback<void(const Result&)> DropCallback;
 
-  // Asynchronously reads the attachment identified by |id|.
+  // Asynchronously reads the attachments identified by |ids|.
   //
-  // |callback| will be invoked when finished. If the attachment does not exist,
-  // |callback|'s Result will be NOT_FOUND and |callback|'s attachment will be
-  // null.
-  virtual void Read(const sync_pb::AttachmentId& id,
+  // |callback| will be invoked when finished. If any of the attachments do not
+  // exist or could not be read, |callback|'s Result will be UNSPECIFIED_ERROR
+  // and |callback| may receive a partial result. That is, AttachmentMap may be
+  // empty or may contain the attachments that were read successfully.
+  //
+  // Reads on individual attachments are treated atomically; |callback| will not
+  // read only part of an attachment.
+  virtual void Read(const AttachmentIdList& ids,
                     const ReadCallback& callback) = 0;
 
-  // Asynchronously writes |bytes| to the store under the given |id|.
+  // Asynchronously writes |attachments| to the store.
+  //
+  // Will not overwrite stored attachments. Attempting to overwrite an
+  // attachment that already exists is not an error.
   //
-  // If the store already contains an attachment with |id| it will be
-  // overwritten. |callback| will be invoked when finished.
-  virtual void Write(const sync_pb::AttachmentId& id,
-                     const scoped_refptr<base::RefCountedMemory>& bytes,
+  // |callback| will be invoked when finished. If any of the attachments could
+  // not be written |callback|'s Result will be UNSPECIFIED_ERROR. When this
+  // happens, some or none of the attachments may have been written
+  // successfully.
+  virtual void Write(const AttachmentList& attachments,
                      const WriteCallback& callback) = 0;
 
-  // Asynchronously drops the attchment with the given id from this store.
+  // Asynchronously drops |attchments| from this store.
+  //
+  // This does not remove attachments from the server.
   //
-  // This does not remove the attachment from the server. |callback| will be
-  // invoked when finished. If the attachment does not exist, |callback|'s
-  // Result will be NOT_FOUND.
-  virtual void Drop(const sync_pb::AttachmentId& id,
+  // |callback| will be invoked when finished. Attempting to drop an attachment
+  // that does not exist is not an error. If any of the existing attachment
+  // could not be dropped, |callback|'s Result will be UNSPECIFIED_ERROR. When
+  // this happens, some or none of the attachments may have been dropped
+  // successfully.
+  virtual void Drop(const AttachmentIdList& ids,
                     const DropCallback& callback) = 0;
 };