123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173 |
- // 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.
- // This file defines FileStream, a basic interface for reading and writing files
- // synchronously or asynchronously with support for seeking to an offset.
- // Note that even when used asynchronously, only one operation is supported at
- // a time.
- #ifndef NET_BASE_FILE_STREAM_H_
- #define NET_BASE_FILE_STREAM_H_
- #include <stdint.h>
- #include <memory>
- #include "base/files/file.h"
- #include "net/base/completion_once_callback.h"
- #include "net/base/net_export.h"
- namespace base {
- class FilePath;
- class TaskRunner;
- }
- namespace net {
- class IOBuffer;
- class NET_EXPORT FileStream {
- public:
- // Uses |task_runner| for asynchronous operations.
- explicit FileStream(const scoped_refptr<base::TaskRunner>& task_runner);
- // Construct a FileStream with an already opened file. |file| must be opened
- // for async reading on Windows, and sync reading everywehere else.
- //
- // Uses |task_runner| for asynchronous operations.
- FileStream(base::File file,
- const scoped_refptr<base::TaskRunner>& task_runner);
- FileStream(const FileStream&) = delete;
- FileStream& operator=(const FileStream&) = delete;
- // The underlying file is closed automatically.
- virtual ~FileStream();
- // Call this method to open the FileStream asynchronously. The remaining
- // methods cannot be used unless the file is opened successfully. Returns
- // ERR_IO_PENDING if the operation is started. If the operation cannot be
- // started then an error code is returned.
- //
- // Once the operation is done, |callback| will be run on the thread where
- // Open() was called, with the result code. open_flags is a bitfield of
- // base::File::Flags.
- //
- // If the file stream is not closed manually, the underlying file will be
- // automatically closed when FileStream is destructed in an asynchronous
- // manner (i.e. the file stream is closed in the background but you don't
- // know when).
- virtual int Open(const base::FilePath& path,
- int open_flags,
- CompletionOnceCallback callback);
- // Returns ERR_IO_PENDING and closes the file asynchronously, calling
- // |callback| when done.
- // It is invalid to request any asynchronous operations while there is an
- // in-flight asynchronous operation.
- virtual int Close(CompletionOnceCallback callback);
- // Returns true if Open succeeded and Close has not been called.
- virtual bool IsOpen() const;
- // Adjust the position from the start of the file where data is read
- // asynchronously. Upon success, ERR_IO_PENDING is returned and |callback|
- // will be run on the thread where Seek() was called with the the stream
- // position relative to the start of the file. Otherwise, an error code is
- // returned. It is invalid to request any asynchronous operations while there
- // is an in-flight asynchronous operation.
- virtual int Seek(int64_t offset, Int64CompletionOnceCallback callback);
- // Call this method to read data from the current stream position
- // asynchronously. Up to buf_len bytes will be copied into buf. (In
- // other words, partial reads are allowed.) Returns the number of bytes
- // copied, 0 if at end-of-file, or an error code if the operation could
- // not be performed.
- //
- // The file must be opened with FLAG_ASYNC, and a non-null
- // callback must be passed to this method. If the read could not
- // complete synchronously, then ERR_IO_PENDING is returned, and the
- // callback will be run on the thread where Read() was called, when the
- // read has completed.
- //
- // It is valid to destroy or close the file stream while there is an
- // asynchronous read in progress. That will cancel the read and allow
- // the buffer to be freed.
- //
- // It is invalid to request any asynchronous operations while there is an
- // in-flight asynchronous operation.
- //
- // This method must not be called if the stream was opened WRITE_ONLY.
- virtual int Read(IOBuffer* buf, int buf_len, CompletionOnceCallback callback);
- // Call this method to write data at the current stream position
- // asynchronously. Up to buf_len bytes will be written from buf. (In
- // other words, partial writes are allowed.) Returns the number of
- // bytes written, or an error code if the operation could not be
- // performed.
- //
- // The file must be opened with FLAG_ASYNC, and a non-null
- // callback must be passed to this method. If the write could not
- // complete synchronously, then ERR_IO_PENDING is returned, and the
- // callback will be run on the thread where Write() was called when
- // the write has completed.
- //
- // It is valid to destroy or close the file stream while there is an
- // asynchronous write in progress. That will cancel the write and allow
- // the buffer to be freed.
- //
- // It is invalid to request any asynchronous operations while there is an
- // in-flight asynchronous operation.
- //
- // This method must not be called if the stream was opened READ_ONLY.
- //
- // Zero byte writes are not allowed.
- virtual int Write(IOBuffer* buf,
- int buf_len,
- CompletionOnceCallback callback);
- // Gets status information about File. May fail synchronously, but never
- // succeeds synchronously.
- //
- // It is invalid to request any asynchronous operations while there is an
- // in-flight asynchronous operation.
- //
- // |file_info| must remain valid until |callback| is invoked.
- virtual int GetFileInfo(base::File::Info* file_info,
- CompletionOnceCallback callback);
- // Forces out a filesystem sync on this file to make sure that the file was
- // written out to disk and is not currently sitting in the buffer. This does
- // not have to be called, it just forces one to happen at the time of
- // calling.
- //
- // The file must be opened with FLAG_ASYNC, and a non-null
- // callback must be passed to this method. If the write could not
- // complete synchronously, then ERR_IO_PENDING is returned, and the
- // callback will be run on the thread where Flush() was called when
- // the write has completed.
- //
- // It is valid to destroy or close the file stream while there is an
- // asynchronous flush in progress. That will cancel the flush and allow
- // the buffer to be freed.
- //
- // It is invalid to request any asynchronous operations while there is an
- // in-flight asynchronous operation.
- //
- // This method should not be called if the stream was opened READ_ONLY.
- virtual int Flush(CompletionOnceCallback callback);
- private:
- class Context;
- // Context performing I/O operations. It was extracted into a separate class
- // to perform asynchronous operations because FileStream can be destroyed
- // before completion of an async operation. Also if a FileStream is destroyed
- // without explicitly calling Close, the file should be closed asynchronously
- // without delaying FileStream's destructor.
- std::unique_ptr<Context> context_;
- };
- } // namespace net
- #endif // NET_BASE_FILE_STREAM_H_
|