device/serial/serial_io_handler.h

   1 // Copyright 2014 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 DEVICE_SERIAL_SERIAL_IO_HANDLER_H_
   6 #define DEVICE_SERIAL_SERIAL_IO_HANDLER_H_
   7
   8 #include "base/callback.h"
   9 #include "base/files/file.h"
  10 #include "base/memory/ref_counted.h"
  11 #include "base/single_thread_task_runner.h"
  12 #include "base/thread_task_runner_handle.h"
  13 #include "base/threading/non_thread_safe.h"
  14 #include "device/serial/buffer.h"
  15 #include "device/serial/serial.mojom.h"
  16
  17 namespace device {
  18
  19 // Provides a simplified interface for performing asynchronous I/O on serial
  20 // devices by hiding platform-specific MessageLoop interfaces. Pending I/O
  21 // operations hold a reference to this object until completion so that memory
  22 // doesn't disappear out from under the OS.
  23 class SerialIoHandler : public base::NonThreadSafe,
  24                         public base::RefCounted<SerialIoHandler> {
  25  public:
  26   // Constructs an instance of some platform-specific subclass.
  27   static scoped_refptr<SerialIoHandler> Create(
  28       scoped_refptr<base::SingleThreadTaskRunner> file_thread_task_runner,
  29       scoped_refptr<base::SingleThreadTaskRunner> ui_thread_task_runner);
  30
  31   typedef base::Callback<void(bool success)> OpenCompleteCallback;
  32
  33   // Initiates an asynchronous Open of the device.
  34   virtual void Open(const std::string& port,
  35                     const serial::ConnectionOptions& options,
  36                     const OpenCompleteCallback& callback);
  37
  38   // Signals that the access request for |port| is complete.
  39   void OnRequestAccessComplete(const std::string& port, bool success);
  40
  41   // Performs an async Read operation. Behavior is undefined if this is called
  42   // while a Read is already pending. Otherwise, the Done or DoneWithError
  43   // method on |buffer| will eventually be called with a result.
  44   void Read(scoped_ptr<WritableBuffer> buffer);
  45
  46   // Performs an async Write operation. Behavior is undefined if this is called
  47   // while a Write is already pending. Otherwise, the Done or DoneWithError
  48   // method on |buffer| will eventually be called with a result.
  49   void Write(scoped_ptr<ReadOnlyBuffer> buffer);
  50
  51   // Indicates whether or not a read is currently pending.
  52   bool IsReadPending() const;
  53
  54   // Indicates whether or not a write is currently pending.
  55   bool IsWritePending() const;
  56
  57   // Attempts to cancel a pending read operation.
  58   void CancelRead(serial::ReceiveError reason);
  59
  60   // Attempts to cancel a pending write operation.
  61   void CancelWrite(serial::SendError reason);
  62
  63   // Flushes input and output buffers.
  64   virtual bool Flush() const = 0;
  65
  66   // Reads current control signals (DCD, CTS, etc.) into an existing
  67   // DeviceControlSignals structure. Returns |true| iff the signals were
  68   // successfully read.
  69   virtual serial::DeviceControlSignalsPtr GetControlSignals() const = 0;
  70
  71   // Sets one or more control signals (DTR and/or RTS). Returns |true| iff
  72   // the signals were successfully set. Unininitialized flags in the
  73   // HostControlSignals structure are left unchanged.
  74   virtual bool SetControlSignals(
  75       const serial::HostControlSignals& control_signals) = 0;
  76
  77   // Performs platform-specific port configuration. Returns |true| iff
  78   // configuration was successful.
  79   bool ConfigurePort(const serial::ConnectionOptions& options);
  80
  81   // Performs a platform-specific port configuration query. Fills values in an
  82   // existing ConnectionInfo. Returns |true| iff port configuration was
  83   // successfully retrieved.
  84   virtual serial::ConnectionInfoPtr GetPortInfo() const = 0;
  85
  86  protected:
  87   explicit SerialIoHandler(
  88       scoped_refptr<base::SingleThreadTaskRunner> file_thread_task_runner,
  89       scoped_refptr<base::SingleThreadTaskRunner> ui_thread_task_runner);
  90   virtual ~SerialIoHandler();
  91
  92   // Performs a platform-specific read operation. This must guarantee that
  93   // ReadCompleted is called when the underlying async operation is completed
  94   // or the SerialIoHandler instance will leak.
  95   // NOTE: Implementations of ReadImpl should never call ReadCompleted directly.
  96   // Use QueueReadCompleted instead to avoid reentrancy.
  97   virtual void ReadImpl() = 0;
  98
  99   // Performs a platform-specific write operation. This must guarantee that
 100   // WriteCompleted is called when the underlying async operation is completed
 101   // or the SerialIoHandler instance will leak.
 102   // NOTE: Implementations of WriteImpl should never call WriteCompleted
 103   // directly. Use QueueWriteCompleted instead to avoid reentrancy.
 104   virtual void WriteImpl() = 0;
 105
 106   // Platform-specific read cancelation.
 107   virtual void CancelReadImpl() = 0;
 108
 109   // Platform-specific write cancelation.
 110   virtual void CancelWriteImpl() = 0;
 111
 112   // Platform-specific port configuration applies options_ to the device.
 113   virtual bool ConfigurePortImpl() = 0;
 114
 115   // Requests access to the underlying serial device, if needed.
 116   virtual void RequestAccess(
 117       const std::string& port,
 118       scoped_refptr<base::SingleThreadTaskRunner> file_task_runner,
 119       scoped_refptr<base::SingleThreadTaskRunner> ui_task_runner);
 120
 121   // Performs platform-specific, one-time port configuration on open.
 122   virtual bool PostOpen();
 123
 124   // Called by the implementation to signal that the active read has completed.
 125   // WARNING: Calling this method can destroy the SerialIoHandler instance
 126   // if the associated I/O operation was the only thing keeping it alive.
 127   void ReadCompleted(int bytes_read, serial::ReceiveError error);
 128
 129   // Called by the implementation to signal that the active write has completed.
 130   // WARNING: Calling this method may destroy the SerialIoHandler instance
 131   // if the associated I/O operation was the only thing keeping it alive.
 132   void WriteCompleted(int bytes_written, serial::SendError error);
 133
 134   // Queues a ReadCompleted call on the current thread. This is used to allow
 135   // ReadImpl to immediately signal completion with 0 bytes and an error,
 136   // without being reentrant.
 137   void QueueReadCompleted(int bytes_read, serial::ReceiveError error);
 138
 139   // Queues a WriteCompleted call on the current thread. This is used to allow
 140   // WriteImpl to immediately signal completion with 0 bytes and an error,
 141   // without being reentrant.
 142   void QueueWriteCompleted(int bytes_written, serial::SendError error);
 143
 144   const base::File& file() const { return file_; }
 145
 146   char* pending_read_buffer() const {
 147     return pending_read_buffer_ ? pending_read_buffer_->GetData() : NULL;
 148   }
 149
 150   uint32_t pending_read_buffer_len() const {
 151     return pending_read_buffer_ ? pending_read_buffer_->GetSize() : 0;
 152   }
 153
 154   serial::ReceiveError read_cancel_reason() const {
 155     return read_cancel_reason_;
 156   }
 157
 158   bool read_canceled() const { return read_canceled_; }
 159
 160   const char* pending_write_buffer() const {
 161     return pending_write_buffer_ ? pending_write_buffer_->GetData() : NULL;
 162   }
 163
 164   uint32_t pending_write_buffer_len() const {
 165     return pending_write_buffer_ ? pending_write_buffer_->GetSize() : 0;
 166   }
 167
 168   serial::SendError write_cancel_reason() const { return write_cancel_reason_; }
 169
 170   bool write_canceled() const { return write_canceled_; }
 171
 172   const serial::ConnectionOptions& options() const { return options_; }
 173
 174   // Possibly fixes up a serial port path name in a platform-specific manner.
 175   static std::string MaybeFixUpPortName(const std::string& port_name);
 176
 177  private:
 178   friend class base::RefCounted<SerialIoHandler>;
 179
 180   void MergeConnectionOptions(const serial::ConnectionOptions& options);
 181
 182   // Continues an Open operation on the FILE thread.
 183   void StartOpen(const std::string& port,
 184                  scoped_refptr<base::SingleThreadTaskRunner> io_task_runner);
 185
 186   // Finalizes an Open operation (continued from StartOpen) on the IO thread.
 187   void FinishOpen(base::File file);
 188
 189   void Close();
 190
 191   // Continues a Close operation on the FILE thread.
 192   static void DoClose(base::File port);
 193
 194   // File for the opened serial device. This value is only modified from the IO
 195   // thread.
 196   base::File file_;
 197
 198   // Currently applied connection options.
 199   serial::ConnectionOptions options_;
 200
 201   scoped_ptr<WritableBuffer> pending_read_buffer_;
 202   serial::ReceiveError read_cancel_reason_;
 203   bool read_canceled_;
 204
 205   scoped_ptr<ReadOnlyBuffer> pending_write_buffer_;
 206   serial::SendError write_cancel_reason_;
 207   bool write_canceled_;
 208
 209   // Callback to handle the completion of a pending Open() request.
 210   OpenCompleteCallback open_complete_;
 211
 212   scoped_refptr<base::SingleThreadTaskRunner> file_thread_task_runner_;
 213   // On Chrome OS, PermissionBrokerClient should be called on the UI thread.
 214   scoped_refptr<base::SingleThreadTaskRunner> ui_thread_task_runner_;
 215
 216   DISALLOW_COPY_AND_ASSIGN(SerialIoHandler);
 217 };
 218
 219 }  // namespace device
 220
 221 #endif  // DEVICE_SERIAL_SERIAL_IO_HANDLER_H_