net: Make UploadDataStream::Read() asynchronous

net/base/upload_data.h

 // Copyright (c) 2012 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.
 
 #ifndef NET_BASE_UPLOAD_DATA_H_
 #define NET_BASE_UPLOAD_DATA_H_
 
 #include <vector>
 
 #include "base/basictypes.h"
@@ skipping 22 matching lines @@
   virtual ~ChunkCallback() {}
 };
 
 //-----------------------------------------------------------------------------
 // A very concrete class representing the data to be uploaded as part of a
 // URLRequest.
 //
 // Until there is a more abstract class for this, this one derives from
 // SupportsUserData to allow users to stash random data by
 // key and ensure its destruction when UploadData is finally deleted.
+//
+// Chunked uploads are handled by repeatedly calling AppendChunk() as data
+// becomes available. When more data becomes available, the ChunkCallback's
+// OnChunkAvailable function is called. The UploadData creator is then
+// responsible for checking if the UploadData stream has more data available, if
+// necessary.
 class NET_EXPORT UploadData
     : public base::RefCounted<UploadData>,
       public base::SupportsUserData {
  public:
   UploadData();
 
   void AppendBytes(const char* bytes, int bytes_len);
 
   void AppendFileRange(const FilePath& file_path,
                        uint64 offset, uint64 length,
                        const base::Time& expected_modification_time);
 
   // Adds the given chunk of bytes to be sent immediately with chunked transfer
   // encoding.
   void AppendChunk(const char* bytes, int bytes_len, bool is_last_chunk);
 
   // Sets the callback to be invoked when a new chunk is available to upload.
   void set_chunk_callback(ChunkCallback* callback);
 
   // Initializes the object to send chunks of upload data over time rather
-  // than all at once.
+  // than all at once. Chunked data may only contain bytes, not files.
   void set_is_chunked(bool set) { is_chunked_ = set; }
   bool is_chunked() const { return is_chunked_; }
 
+  // set_last_chunk_appended() is only used for serialization.
   void set_last_chunk_appended(bool set) { last_chunk_appended_ = set; }
   bool last_chunk_appended() const { return last_chunk_appended_; }
 
   const std::vector<UploadElement>* elements() const {
     return &elements_;
   }
 
   std::vector<UploadElement>* elements_mutable() {
     return &elements_;
   }
@@ skipping 20 matching lines @@
   ChunkCallback* chunk_callback_;
   bool is_chunked_;
   bool last_chunk_appended_;
 
   DISALLOW_COPY_AND_ASSIGN(UploadData);
 };
 
 }  // namespace net
 
 #endif  // NET_BASE_UPLOAD_DATA_H_