file_stream.h 7.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173
  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. // This file defines FileStream, a basic interface for reading and writing files
  5. // synchronously or asynchronously with support for seeking to an offset.
  6. // Note that even when used asynchronously, only one operation is supported at
  7. // a time.
  8. #ifndef NET_BASE_FILE_STREAM_H_
  9. #define NET_BASE_FILE_STREAM_H_
  10. #include <stdint.h>
  11. #include <memory>
  12. #include "base/files/file.h"
  13. #include "net/base/completion_once_callback.h"
  14. #include "net/base/net_export.h"
  15. namespace base {
  16. class FilePath;
  17. class TaskRunner;
  18. }
  19. namespace net {
  20. class IOBuffer;
  21. class NET_EXPORT FileStream {
  22. public:
  23. // Uses |task_runner| for asynchronous operations.
  24. explicit FileStream(const scoped_refptr<base::TaskRunner>& task_runner);
  25. // Construct a FileStream with an already opened file. |file| must be opened
  26. // for async reading on Windows, and sync reading everywehere else.
  27. //
  28. // Uses |task_runner| for asynchronous operations.
  29. FileStream(base::File file,
  30. const scoped_refptr<base::TaskRunner>& task_runner);
  31. FileStream(const FileStream&) = delete;
  32. FileStream& operator=(const FileStream&) = delete;
  33. // The underlying file is closed automatically.
  34. virtual ~FileStream();
  35. // Call this method to open the FileStream asynchronously. The remaining
  36. // methods cannot be used unless the file is opened successfully. Returns
  37. // ERR_IO_PENDING if the operation is started. If the operation cannot be
  38. // started then an error code is returned.
  39. //
  40. // Once the operation is done, |callback| will be run on the thread where
  41. // Open() was called, with the result code. open_flags is a bitfield of
  42. // base::File::Flags.
  43. //
  44. // If the file stream is not closed manually, the underlying file will be
  45. // automatically closed when FileStream is destructed in an asynchronous
  46. // manner (i.e. the file stream is closed in the background but you don't
  47. // know when).
  48. virtual int Open(const base::FilePath& path,
  49. int open_flags,
  50. CompletionOnceCallback callback);
  51. // Returns ERR_IO_PENDING and closes the file asynchronously, calling
  52. // |callback| when done.
  53. // It is invalid to request any asynchronous operations while there is an
  54. // in-flight asynchronous operation.
  55. virtual int Close(CompletionOnceCallback callback);
  56. // Returns true if Open succeeded and Close has not been called.
  57. virtual bool IsOpen() const;
  58. // Adjust the position from the start of the file where data is read
  59. // asynchronously. Upon success, ERR_IO_PENDING is returned and |callback|
  60. // will be run on the thread where Seek() was called with the the stream
  61. // position relative to the start of the file. Otherwise, an error code is
  62. // returned. It is invalid to request any asynchronous operations while there
  63. // is an in-flight asynchronous operation.
  64. virtual int Seek(int64_t offset, Int64CompletionOnceCallback callback);
  65. // Call this method to read data from the current stream position
  66. // asynchronously. Up to buf_len bytes will be copied into buf. (In
  67. // other words, partial reads are allowed.) Returns the number of bytes
  68. // copied, 0 if at end-of-file, or an error code if the operation could
  69. // not be performed.
  70. //
  71. // The file must be opened with FLAG_ASYNC, and a non-null
  72. // callback must be passed to this method. If the read could not
  73. // complete synchronously, then ERR_IO_PENDING is returned, and the
  74. // callback will be run on the thread where Read() was called, when the
  75. // read has completed.
  76. //
  77. // It is valid to destroy or close the file stream while there is an
  78. // asynchronous read in progress. That will cancel the read and allow
  79. // the buffer to be freed.
  80. //
  81. // It is invalid to request any asynchronous operations while there is an
  82. // in-flight asynchronous operation.
  83. //
  84. // This method must not be called if the stream was opened WRITE_ONLY.
  85. virtual int Read(IOBuffer* buf, int buf_len, CompletionOnceCallback callback);
  86. // Call this method to write data at the current stream position
  87. // asynchronously. Up to buf_len bytes will be written from buf. (In
  88. // other words, partial writes are allowed.) Returns the number of
  89. // bytes written, or an error code if the operation could not be
  90. // performed.
  91. //
  92. // The file must be opened with FLAG_ASYNC, and a non-null
  93. // callback must be passed to this method. If the write could not
  94. // complete synchronously, then ERR_IO_PENDING is returned, and the
  95. // callback will be run on the thread where Write() was called when
  96. // the write has completed.
  97. //
  98. // It is valid to destroy or close the file stream while there is an
  99. // asynchronous write in progress. That will cancel the write and allow
  100. // the buffer to be freed.
  101. //
  102. // It is invalid to request any asynchronous operations while there is an
  103. // in-flight asynchronous operation.
  104. //
  105. // This method must not be called if the stream was opened READ_ONLY.
  106. //
  107. // Zero byte writes are not allowed.
  108. virtual int Write(IOBuffer* buf,
  109. int buf_len,
  110. CompletionOnceCallback callback);
  111. // Gets status information about File. May fail synchronously, but never
  112. // succeeds synchronously.
  113. //
  114. // It is invalid to request any asynchronous operations while there is an
  115. // in-flight asynchronous operation.
  116. //
  117. // |file_info| must remain valid until |callback| is invoked.
  118. virtual int GetFileInfo(base::File::Info* file_info,
  119. CompletionOnceCallback callback);
  120. // Forces out a filesystem sync on this file to make sure that the file was
  121. // written out to disk and is not currently sitting in the buffer. This does
  122. // not have to be called, it just forces one to happen at the time of
  123. // calling.
  124. //
  125. // The file must be opened with FLAG_ASYNC, and a non-null
  126. // callback must be passed to this method. If the write could not
  127. // complete synchronously, then ERR_IO_PENDING is returned, and the
  128. // callback will be run on the thread where Flush() was called when
  129. // the write has completed.
  130. //
  131. // It is valid to destroy or close the file stream while there is an
  132. // asynchronous flush in progress. That will cancel the flush and allow
  133. // the buffer to be freed.
  134. //
  135. // It is invalid to request any asynchronous operations while there is an
  136. // in-flight asynchronous operation.
  137. //
  138. // This method should not be called if the stream was opened READ_ONLY.
  139. virtual int Flush(CompletionOnceCallback callback);
  140. private:
  141. class Context;
  142. // Context performing I/O operations. It was extracted into a separate class
  143. // to perform asynchronous operations because FileStream can be destroyed
  144. // before completion of an async operation. Also if a FileStream is destroyed
  145. // without explicitly calling Close, the file should be closed asynchronously
  146. // without delaying FileStream's destructor.
  147. std::unique_ptr<Context> context_;
  148. };
  149. } // namespace net
  150. #endif // NET_BASE_FILE_STREAM_H_