1 // Copyright 2013 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.
5 #ifndef CHROME_BROWSER_EXTENSIONS_API_SERIAL_SERIAL_IO_HANDLER_H_
6 #define CHROME_BROWSER_EXTENSIONS_API_SERIAL_SERIAL_IO_HANDLER_H_
8 #include "base/callback.h"
9 #include "base/files/file.h"
10 #include "base/memory/ref_counted.h"
11 #include "base/threading/non_thread_safe.h"
12 #include "device/serial/serial.mojom.h"
13 #include "net/base/io_buffer.h"
15 namespace extensions
{
17 // Provides a simplified interface for performing asynchronous I/O on serial
18 // devices by hiding platform-specific MessageLoop interfaces. Pending I/O
19 // operations hold a reference to this object until completion so that memory
20 // doesn't disappear out from under the OS.
21 class SerialIoHandler
: public base::NonThreadSafe
,
22 public base::RefCounted
<SerialIoHandler
> {
24 // Constructs an instance of some platform-specific subclass.
25 static scoped_refptr
<SerialIoHandler
> Create();
27 typedef base::Callback
<void(bool success
)> OpenCompleteCallback
;
29 // Called with a string of bytes read, and a result code. Note that an error
30 // result does not necessarily imply 0 bytes read.
31 typedef base::Callback
<
32 void(const std::string
& data
, device::serial::ReceiveError error
)>
35 // Called with the number of bytes written and a result code. Note that an
36 // error result does not necessarily imply 0 bytes written.
37 typedef base::Callback
<
38 void(int bytes_written
, device::serial::SendError error
)>
39 WriteCompleteCallback
;
41 // Initializes the handler on the current message loop. Must be called exactly
42 // once before performing any I/O through the handler.
43 virtual void Initialize(const ReadCompleteCallback
& read_callback
,
44 const WriteCompleteCallback
& write_callback
);
46 // Initiates an asynchronous Open of the device.
47 virtual void Open(const std::string
& port
,
48 const OpenCompleteCallback
& callback
);
50 // Performs an async Read operation. Behavior is undefined if this is called
51 // while a Read is already pending. Otherwise, the ReadCompleteCallback
52 // (see above) will eventually be called with a result.
53 void Read(int max_bytes
);
55 // Performs an async Write operation. Behavior is undefined if this is called
56 // while a Write is already pending. Otherwise, the WriteCompleteCallback
57 // (see above) will eventually be called with a result.
58 void Write(const std::string
& data
);
60 // Indicates whether or not a read is currently pending.
61 bool IsReadPending() const;
63 // Indicates whether or not a write is currently pending.
64 bool IsWritePending() const;
66 // Attempts to cancel a pending read operation.
67 void CancelRead(device::serial::ReceiveError reason
);
69 // Attempts to cancel a pending write operation.
70 void CancelWrite(device::serial::SendError reason
);
72 // Flushes input and output buffers.
73 virtual bool Flush() const = 0;
75 // Reads current control signals (DCD, CTS, etc.) into an existing
76 // DeviceControlSignals structure. Returns |true| iff the signals were
78 virtual device::serial::DeviceControlSignalsPtr
GetControlSignals() const = 0;
80 // Sets one or more control signals (DTR and/or RTS). Returns |true| iff
81 // the signals were successfully set. Unininitialized flags in the
82 // HostControlSignals structure are left unchanged.
83 virtual bool SetControlSignals(
84 const device::serial::HostControlSignals
& control_signals
) = 0;
86 // Performs platform-specific port configuration. Returns |true| iff
87 // configuration was successful.
88 virtual bool ConfigurePort(
89 const device::serial::ConnectionOptions
& options
) = 0;
91 // Performs a platform-specific port configuration query. Fills values in an
92 // existing ConnectionInfo. Returns |true| iff port configuration was
93 // successfully retrieved.
94 virtual device::serial::ConnectionInfoPtr
GetPortInfo() const = 0;
98 virtual ~SerialIoHandler();
100 // Performs a platform-specific read operation. This must guarantee that
101 // ReadCompleted is called when the underlying async operation is completed
102 // or the SerialIoHandler instance will leak.
103 // NOTE: Implementations of ReadImpl should never call ReadCompleted directly.
104 // Use QueueReadCompleted instead to avoid reentrancy.
105 virtual void ReadImpl() = 0;
107 // Performs a platform-specific write operation. This must guarantee that
108 // WriteCompleted is called when the underlying async operation is completed
109 // or the SerialIoHandler instance will leak.
110 // NOTE: Implementations of Writempl should never call WriteCompleted
111 // directly. Use QueueWriteCompleted instead to avoid reentrancy.
112 virtual void WriteImpl() = 0;
114 // Platform-specific read cancelation.
115 virtual void CancelReadImpl() = 0;
117 // Platform-specific write cancelation.
118 virtual void CancelWriteImpl() = 0;
120 // Performs platform-specific, one-time port configuration on open.
121 virtual bool PostOpen();
123 // Called by the implementation to signal that the active read has completed.
124 // WARNING: Calling this method can destroy the SerialIoHandler instance
125 // if the associated I/O operation was the only thing keeping it alive.
126 void ReadCompleted(int bytes_read
, device::serial::ReceiveError error
);
128 // Called by the implementation to signal that the active write has completed.
129 // WARNING: Calling this method may destroy the SerialIoHandler instance
130 // if the associated I/O operation was the only thing keeping it alive.
131 void WriteCompleted(int bytes_written
, device::serial::SendError error
);
133 // Queues a ReadCompleted call on the current thread. This is used to allow
134 // ReadImpl to immediately signal completion with 0 bytes and an error,
135 // without being reentrant.
136 void QueueReadCompleted(int bytes_read
, device::serial::ReceiveError error
);
138 // Queues a WriteCompleted call on the current thread. This is used to allow
139 // WriteImpl to immediately signal completion with 0 bytes and an error,
140 // without being reentrant.
141 void QueueWriteCompleted(int bytes_written
, device::serial::SendError error
);
143 const base::File
& file() const { return file_
; }
145 net::IOBuffer
* pending_read_buffer() const {
146 return pending_read_buffer_
.get();
149 int pending_read_buffer_len() const {
150 return pending_read_buffer_len_
;
153 device::serial::ReceiveError
read_cancel_reason() const {
154 return read_cancel_reason_
;
157 bool read_canceled() const {
158 return read_canceled_
;
161 net::IOBuffer
* pending_write_buffer() const {
162 return pending_write_buffer_
.get();
165 int pending_write_buffer_len() const {
166 return pending_write_buffer_len_
;
169 device::serial::SendError
write_cancel_reason() const {
170 return write_cancel_reason_
;
173 bool write_canceled() const {
174 return write_canceled_
;
177 // Possibly fixes up a serial port path name in a platform-specific manner.
178 static std::string
MaybeFixUpPortName(const std::string
& port_name
);
181 friend class base::RefCounted
<SerialIoHandler
>;
183 // Continues an Open operation on the FILE thread.
184 void StartOpen(const std::string
& port
);
186 // Finalizes an Open operation (continued from StartOpen) on the IO thread.
187 void FinishOpen(base::File file
);
191 // Continues a Close operation on the FILE thread.
192 static void DoClose(base::File port
);
194 // File for the opened serial device. This value is only modified from the IO
198 scoped_refptr
<net::IOBuffer
> pending_read_buffer_
;
199 int pending_read_buffer_len_
;
200 device::serial::ReceiveError read_cancel_reason_
;
203 scoped_refptr
<net::IOBuffer
> pending_write_buffer_
;
204 int pending_write_buffer_len_
;
205 device::serial::SendError write_cancel_reason_
;
206 bool write_canceled_
;
208 ReadCompleteCallback read_complete_
;
209 WriteCompleteCallback write_complete_
;
211 // Callback to handle the completion of a pending Open() request.
212 OpenCompleteCallback open_complete_
;
214 DISALLOW_COPY_AND_ASSIGN(SerialIoHandler
);
217 } // namespace extensions
219 #endif // CHROME_BROWSER_EXTENSIONS_API_SERIAL_SERIAL_IO_HANDLER_H_