chrome/common/extensions/api/serial.idl

   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 // Use the <code>chrome.serial</code> API to read from and write to a device
   6 // connected to a serial port.
   7 namespace serial {
   8
   9   dictionary DeviceInfo {
  10     // The device's system path. This should be passed as the <code>path</code>
  11     // argument to <code>chrome.serial.connect</code> in order to connect to
  12     // this device.
  13     DOMString path;
  14   };
  15
  16   callback GetDevicesCallback = void (DeviceInfo[] ports);
  17
  18   enum DataBits { seven, eight };
  19   enum ParityBit { no, odd, even };
  20   enum StopBits { one, two };
  21
  22   dictionary ConnectionOptions {
  23     // Flag indicating whether or not the connection should be left open when
  24     // the application is suspended (see
  25     // <a href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App
  26     // Lifecycle</a>). The default value is "false." When the application is
  27     // loaded, any serial connections previously opened with persistent=true
  28     // can be fetched with <code>getConnections</code>.
  29     boolean? persistent;
  30
  31     // An application-defined string to associate with the connection.
  32     DOMString? name;
  33
  34     // The size of the buffer used to receive data. The default value is 4096.
  35     long? bufferSize;
  36
  37     // The requested bitrate of the connection to be opened. For compatibility
  38     // with the widest range of hardware, this number should match one of
  39     // commonly-available bitrates, such as 110, 300, 1200, 2400, 4800, 9600,
  40     // 14400, 19200, 38400, 57600, 115200. There is no guarantee, of course,
  41     // that the device connected to the serial port will support the requested
  42     // bitrate, even if the port itself supports that bitrate. <code>9600</code>
  43     // will be passed by default.
  44     long? bitrate;
  45
  46     // <code>"eight"</code> will be passed by default.
  47     DataBits? dataBits;
  48
  49     // <code>"no"</code> will be passed by default.
  50     ParityBit? parityBit;
  51
  52     // <code>"one"</code> will be passed by default.
  53     StopBits? stopBits;
  54
  55     // Flag indicating whether or not to enable RTS/CTS hardware flow control.
  56     // Defaults to false.
  57     boolean? ctsFlowControl;
  58
  59     // The maximum amount of time (in milliseconds) to wait for new data before
  60     // raising an <code>onReceiveError</code> event with a "timeout" error.
  61     // If zero, receive timeout errors will not be raised for the connection.
  62     // Defaults to 0.
  63     long? receiveTimeout;
  64
  65     // The maximum amount of time (in milliseconds) to wait for a
  66     // <code>send</code> operation to complete before calling the callback with
  67     // a "timeout" error. If zero, send timeout errors will not be triggered.
  68     // Defaults to 0.
  69     long? sendTimeout;
  70   };
  71
  72   // Result of the <code>getInfo</code> method.
  73   dictionary ConnectionInfo {
  74     // The id of the serial port connection.
  75     long connectionId;
  76
  77     // Flag indicating whether the connection is blocked from firing onReceive
  78     // events.
  79     boolean paused;
  80
  81     // See <code>ConnectionOptions.persistent</code>
  82     boolean persistent;
  83
  84     // See <code>ConnectionOptions.name</code>
  85     DOMString name;
  86
  87     // See <code>ConnectionOptions.bufferSize</code>
  88     long bufferSize;
  89
  90     // See <code>ConnectionOptions.receiveTimeout</code>
  91     long receiveTimeout;
  92
  93     // See <code>ConnectionOptions.sendTimeout</code>
  94     long sendTimeout;
  95
  96     // See <code>ConnectionOptions.bitrate</code>. This field may be omitted
  97     // or inaccurate if a non-standard bitrate is in use, or if an error
  98     // occurred while querying the underlying device.
  99     long? bitrate;
 100
 101     // See <code>ConnectionOptions.dataBits</code>. This field may be omitted
 102     // if an error occurred while querying the underlying device.
 103     DataBits? dataBits;
 104
 105     // See <code>ConnectionOptions.parityBit</code>. This field may be omitted
 106     // if an error occurred while querying the underlying device.
 107     ParityBit? parityBit;
 108
 109     // See <code>ConnectionOptions.stopBits</code>. This field may be omitted
 110     // if an error occurred while querying the underlying device.
 111     StopBits? stopBits;
 112
 113     // See <code>ConnectionOptions.ctsFlowControl</code>. This field may be
 114     // omitted if an error occurred while querying the underlying device.
 115     boolean? ctsFlowControl;
 116   };
 117
 118   // Callback from the <code>connect</code> method;
 119   callback ConnectCallback = void (ConnectionInfo connectionInfo);
 120
 121   // Callback from the <code>update</code> method.
 122   callback UpdateCallback = void (boolean result);
 123
 124   // Callback from the <code>disconnect</code> method. Returns true if the
 125   // operation was successful.
 126   callback DisconnectCallback = void (boolean result);
 127
 128   // Callback from the <code>setPaused</code> method.
 129   callback SetPausedCallback = void ();
 130
 131   // Callback from the <code>getInfo</code> method.
 132   callback GetInfoCallback = void (ConnectionInfo connectionInfo);
 133
 134   // Callback from the <code>getConnections</code> method.
 135   callback GetConnectionsCallback = void (ConnectionInfo[] connectionInfos);
 136
 137   enum SendError {
 138     // The connection was disconnected.
 139     disconnected,
 140
 141     // A send was already pending.
 142     pending,
 143
 144     // The send timed out.
 145     timeout,
 146
 147     // A system error occurred and the connection may be unrecoverable.
 148     system_error
 149   };
 150
 151   dictionary SendInfo {
 152     // The number of bytes sent.
 153     long bytesSent;
 154
 155     // An error code if an error occurred.
 156     SendError? error;
 157   };
 158
 159   callback SendCallback = void (SendInfo sendInfo);
 160
 161   callback FlushCallback = void (boolean result);
 162
 163   // The set of control signals which may be sent to a connected serial device
 164   // using <code>setControlSignals</code>. Note that support for these signals
 165   // is device-dependent.
 166   dictionary HostControlSignals {
 167     // DTR (Data Terminal Ready).
 168     boolean? dtr;
 169
 170     // RTS (Request To Send).
 171     boolean? rts;
 172   };
 173
 174   // The set of control signals which may be set by a connected serial device.
 175   // These can be queried using <code>getControlSignals</code>. Note that
 176   // support for these signals is device-dependent.
 177   dictionary DeviceControlSignals {
 178     // DCD (Data Carrier Detect) or RLSD (Receive Line Signal/ Detect).
 179     boolean dcd;
 180
 181     // CTS (Clear To Send).
 182     boolean cts;
 183
 184     // RI (Ring Indicator).
 185     boolean ri;
 186
 187     // DSR (Data Set Ready).
 188     boolean dsr;
 189   };
 190
 191   // Returns a snapshot of current control signals.
 192   callback GetControlSignalsCallback = void (DeviceControlSignals signals);
 193
 194   // Returns true if operation was successful.
 195   callback SetControlSignalsCallback = void (boolean result);
 196
 197   // Data from an <code>onReceive</code> event.
 198   dictionary ReceiveInfo {
 199     // The connection identifier.
 200     long connectionId;
 201
 202     // The data received.
 203     ArrayBuffer data;
 204   };
 205
 206   enum ReceiveError {
 207     // The connection was disconnected.
 208     disconnected,
 209
 210     // No data has been received for <code>receiveTimeout</code> milliseconds.
 211     timeout,
 212
 213     // The device was most likely disconnected from the host.
 214     device_lost,
 215
 216     // A system error occurred and the connection may be unrecoverable.
 217     system_error
 218   };
 219
 220   // Data from an <code>onReceiveError</code> event.
 221   dictionary ReceiveErrorInfo {
 222     // The connection identifier.
 223     long connectionId;
 224
 225     // An error code indicating what went wrong.
 226     ReceiveError error;
 227   };
 228
 229   interface Functions {
 230     // Returns information about available serial devices on the system.
 231     // The list is regenerated each time this method is called.
 232     // |callback| : Called with the list of <code>DeviceInfo</code> objects.
 233     static void getDevices(GetDevicesCallback callback);
 234
 235     // Connects to a given serial port.
 236     // |path| : The system path of the serial port to open.
 237     // |options| : Port configuration options.
 238     // |callback| : Called when the connection has been opened.
 239     static void connect(DOMString path,
 240                         optional ConnectionOptions options,
 241                         ConnectCallback callback);
 242
 243     // Update the option settings on an open serial port connection.
 244     // |connectionId| : The id of the opened connection.
 245     // |options| : Port configuration options.
 246     // |callback| : Called when the configuation has completed.
 247     static void update(long connectionId,
 248                        ConnectionOptions options,
 249                        UpdateCallback callback);
 250
 251     // Disconnects from a serial port.
 252     // |connectionId| : The id of the opened connection.
 253     // |callback| : Called when the connection has been closed.
 254     static void disconnect(long connectionId, DisconnectCallback callback);
 255
 256     // Pauses or unpauses an open connection.
 257     // |connectionId| : The id of the opened connection.
 258     // |paused| : Flag to indicate whether to pause or unpause.
 259     // |callback| : Called when the connection has been successfully paused or
 260     //              unpaused.
 261     static void setPaused(long connectionId,
 262                           boolean paused,
 263                           SetPausedCallback callback);
 264
 265     // Retrieves the state of a given connection.
 266     // |connectionId| : The id of the opened connection.
 267     // |callback| : Called with connection state information when available.
 268     static void getInfo(long connectionId, GetInfoCallback callback);
 269
 270     // Retrieves the list of currently opened serial port connections owned by
 271     // the application.
 272     // |callback| : Called with the list of connections when available.
 273     static void getConnections(GetConnectionsCallback callback);
 274
 275     // Writes data to the given connection.
 276     // |connectionId| : The id of the connection.
 277     // |data| : The data to send.
 278     // |callback| : Called when the operation has completed.
 279     static void send(long connectionId,
 280                      ArrayBuffer data,
 281                      SendCallback callback);
 282
 283     // Flushes all bytes in the given connection's input and output buffers.
 284     static void flush(long connectionId, FlushCallback callback);
 285
 286     // Retrieves the state of control signals on a given connection.
 287     // |connectionId| : The id of the connection.
 288     // |callback| : Called when the control signals are available.
 289     static void getControlSignals(long connectionId,
 290                                   GetControlSignalsCallback callback);
 291
 292     // Sets the state of control signals on a given connection.
 293     // |connectionId| : The id of the connection.
 294     // |signals| : The set of signal changes to send to the device.
 295     // |callback| : Called once the control signals have been set.
 296     static void setControlSignals(long connectionId,
 297                                   HostControlSignals signals,
 298                                   SetControlSignalsCallback callback);
 299   };
 300
 301   interface Events {
 302     // Event raised when data has been read from the connection.
 303     // |info| : Event data.
 304     static void onReceive(ReceiveInfo info);
 305
 306     // Event raised when an error occurred while the runtime was waiting for
 307     // data on the serial port. Once this event is raised, the connection may be
 308     // set to <code>paused</code>. A <code>"timeout"</code> error does not pause
 309     // the connection.
 310     static void onReceiveError(ReceiveErrorInfo info);
 311   };
 312 };