extensions/common/api/serial.idl

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