net/base/upload_data_stream.h

   1 // Copyright (c) 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 NET_BASE_UPLOAD_DATA_STREAM_H_
   6 #define NET_BASE_UPLOAD_DATA_STREAM_H_
   7
   8 #include "base/basictypes.h"
   9 #include "base/macros.h"
  10 #include "base/memory/scoped_vector.h"
  11 #include "net/base/completion_callback.h"
  12 #include "net/base/net_export.h"
  13
  14 namespace net {
  15
  16 class DrainableIOBuffer;
  17 class IOBuffer;
  18 class UploadElementReader;
  19
  20 // A class for retrieving all data to be sent as a request body. Supports both
  21 // chunked and non-chunked uploads.
  22 class NET_EXPORT UploadDataStream {
  23  public:
  24   // |identifier| identifies a particular upload instance, which is used by the
  25   // cache to formulate a cache key. This value should be unique across browser
  26   // sessions. A value of 0 is used to indicate an unspecified identifier.
  27   UploadDataStream(bool is_chunked, int64_t identifier);
  28
  29   virtual ~UploadDataStream();
  30
  31   // Initializes the stream. This function must be called before calling any
  32   // other method. It is not valid to call any method (other than the
  33   // destructor) if Init() fails. This method can be called multiple times.
  34   // Calling this method after an Init() success results in resetting the
  35   // state (i.e. the stream is rewound).
  36   //
  37   // Does the initialization synchronously and returns the result if possible,
  38   // otherwise returns ERR_IO_PENDING and runs the callback with the result.
  39   //
  40   // Returns OK on success. Returns ERR_UPLOAD_FILE_CHANGED if the expected
  41   // file modification time is set (usually not set, but set for sliced
  42   // files) and the target file is changed.
  43   int Init(const CompletionCallback& callback);
  44
  45   // When possible, reads up to |buf_len| bytes synchronously from the upload
  46   // data stream to |buf| and returns the number of bytes read; otherwise,
  47   // returns ERR_IO_PENDING and calls |callback| with the number of bytes read.
  48   // Partial reads are allowed. Zero is returned on a call to Read when there
  49   // are no remaining bytes in the stream, and IsEof() will return true
  50   // hereafter.
  51   //
  52   // If there's less data to read than we initially observed (i.e. the actual
  53   // upload data is smaller than size()), zeros are padded to ensure that
  54   // size() bytes can be read, which can happen for TYPE_FILE payloads.
  55   //
  56   // Reads are currently not allowed to fail - they must either return
  57   // a value >= 0 or ERR_IO_PENDING, and call OnReadCompleted with a
  58   // value >= 0.
  59   // TODO(mmenke):  Investigate letting reads fail.
  60   int Read(IOBuffer* buf, int buf_len, const CompletionCallback& callback);
  61
  62   // Returns the total size of the data stream and the current position.
  63   // When the data is chunked, always returns zero. Must always return the same
  64   // value after each call to Initialize().
  65   uint64_t size() const { return total_size_; }
  66   uint64_t position() const { return current_position_; }
  67
  68   // See constructor for description.
  69   int64_t identifier() const { return identifier_; }
  70
  71   bool is_chunked() const { return is_chunked_; }
  72
  73   // Returns true if all data has been consumed from this upload data
  74   // stream. For chunked uploads, returns false until the first read attempt.
  75   // This makes some state machines a little simpler.
  76   bool IsEOF() const;
  77
  78   // Cancels all pending callbacks, and resets state. Any IOBuffer currently
  79   // being read to is not safe for future use, as it may be in use on another
  80   // thread.
  81   void Reset();
  82
  83   // Returns true if the upload data in the stream is entirely in memory, and
  84   // all read requests will succeed synchronously. Expected to return false for
  85   // chunked requests.
  86   virtual bool IsInMemory() const;
  87
  88   // Returns a list of element readers owned by |this|, if it has any.
  89   virtual const ScopedVector<UploadElementReader>*
  90       GetElementReaders() const;
  91
  92  protected:
  93   // Must be called by subclasses when InitInternal and ReadInternal complete
  94   // asynchronously.
  95   void OnInitCompleted(int result);
  96   void OnReadCompleted(int result);
  97
  98   // Must be called before InitInternal completes, for non-chunked uploads.
  99   // Must not be called for chunked uploads.
 100   void SetSize(uint64_t size);
 101
 102   // Must be called for chunked uploads before the final ReadInternal call
 103   // completes. Must not be called for non-chunked uploads.
 104   void SetIsFinalChunk();
 105
 106  private:
 107   // See Init(). If it returns ERR_IO_PENDING, OnInitCompleted must be called
 108   // once it completes. If the upload is not chunked, SetSize must be called
 109   // before it completes.
 110   virtual int InitInternal() = 0;
 111
 112   // See Read(). For chunked uploads, must call SetIsFinalChunk if this is the
 113   // final chunk. For non-chunked uploads, the UploadDataStream determins which
 114   // read is the last based on size. Must read 1 or more bytes on every call,
 115   // though the final chunk may be 0 bytes, for chunked requests. If it returns
 116   // ERR_IO_PENDING, OnInitCompleted must be called once it completes. Must not
 117   // return any error, other than ERR_IO_PENDING.
 118   virtual int ReadInternal(IOBuffer* buf, int buf_len) = 0;
 119
 120   // Resets state and cancels any pending callbacks. Guaranteed to be called
 121   // before all but the first call to InitInternal.
 122   virtual void ResetInternal() = 0;
 123
 124   uint64_t total_size_;
 125   uint64_t current_position_;
 126
 127   const int64_t identifier_;
 128
 129   const bool is_chunked_;
 130
 131   // True if the initialization was successful.
 132   bool initialized_successfully_;
 133
 134   bool is_eof_;
 135
 136   CompletionCallback callback_;
 137
 138   DISALLOW_COPY_AND_ASSIGN(UploadDataStream);
 139 };
 140
 141 }  // namespace net
 142
 143 #endif  // NET_BASE_UPLOAD_DATA_STREAM_H_