src/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     // 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   // The set of control signals which may be sent to a connected serial device
 175   // using <code>setControlSignals</code>. Note that support for these signals
 176   // is device-dependent.
 177   dictionary HostControlSignals {
 178     // DTR (Data Terminal Ready).
 179     boolean? dtr;
 180
 181     // RTS (Request To Send).
 182     boolean? rts;
 183   };
 184
 185   // The set of control signals which may be set by a connected serial device.
 186   // These can be queried using <code>getControlSignals</code>. Note that
 187   // support for these signals is device-dependent.
 188   dictionary DeviceControlSignals {
 189     // DCD (Data Carrier Detect) or RLSD (Receive Line Signal/ Detect).
 190     boolean dcd;
 191
 192     // CTS (Clear To Send).
 193     boolean cts;
 194
 195     // RI (Ring Indicator).
 196     boolean ri;
 197
 198     // DSR (Data Set Ready).
 199     boolean dsr;
 200   };
 201
 202   // Returns a snapshot of current control signals.
 203   callback GetControlSignalsCallback = void (DeviceControlSignals signals);
 204
 205   // Returns true if operation was successful.
 206   callback SetControlSignalsCallback = void (boolean result);
 207
 208   // Data from an <code>onReceive</code> event.
 209   dictionary ReceiveInfo {
 210     // The connection identifier.
 211     long connectionId;
 212
 213     // The data received.
 214     ArrayBuffer data;
 215   };
 216
 217   enum ReceiveError {
 218     // The connection was disconnected.
 219     disconnected,
 220
 221     // No data has been received for <code>receiveTimeout</code> milliseconds.
 222     timeout,
 223
 224     // The device was most likely disconnected from the host.
 225     device_lost,
 226
 227     // A system error occurred and the connection may be unrecoverable.
 228     system_error
 229   };
 230
 231   // Data from an <code>onReceiveError</code> event.
 232   dictionary ReceiveErrorInfo {
 233     // The connection identifier.
 234     long connectionId;
 235
 236     // An error code indicating what went wrong.
 237     ReceiveError error;
 238   };
 239
 240   interface Functions {
 241     // Returns information about available serial devices on the system.
 242     // The list is regenerated each time this method is called.
 243     // |callback| : Called with the list of <code>DeviceInfo</code> objects.
 244     static void getDevices(GetDevicesCallback callback);
 245
 246     // Connects to a given serial port.
 247     // |path| : The system path of the serial port to open.
 248     // |options| : Port configuration options.
 249     // |callback| : Called when the connection has been opened.
 250     static void connect(DOMString path,
 251                         optional ConnectionOptions options,
 252                         ConnectCallback callback);
 253
 254     // Update the option settings on an open serial port connection.
 255     // |connectionId| : The id of the opened connection.
 256     // |options| : Port configuration options.
 257     // |callback| : Called when the configuation has completed.
 258     static void update(long connectionId,
 259                        ConnectionOptions options,
 260                        UpdateCallback callback);
 261
 262     // Disconnects from a serial port.
 263     // |connectionId| : The id of the opened connection.
 264     // |callback| : Called when the connection has been closed.
 265     static void disconnect(long connectionId, DisconnectCallback callback);
 266
 267     // Pauses or unpauses an open connection.
 268     // |connectionId| : The id of the opened connection.
 269     // |paused| : Flag to indicate whether to pause or unpause.
 270     // |callback| : Called when the connection has been successfully paused or
 271     //              unpaused.
 272     static void setPaused(long connectionId,
 273                           boolean paused,
 274                           SetPausedCallback callback);
 275
 276     // Retrieves the state of a given connection.
 277     // |connectionId| : The id of the opened connection.
 278     // |callback| : Called with connection state information when available.
 279     static void getInfo(long connectionId, GetInfoCallback callback);
 280
 281     // Retrieves the list of currently opened serial port connections owned by
 282     // the application.
 283     // |callback| : Called with the list of connections when available.
 284     static void getConnections(GetConnectionsCallback callback);
 285
 286     // Writes data to the given connection.
 287     // |connectionId| : The id of the connection.
 288     // |data| : The data to send.
 289     // |callback| : Called when the operation has completed.
 290     static void send(long connectionId,
 291                      ArrayBuffer data,
 292                      SendCallback callback);
 293
 294     // Flushes all bytes in the given connection's input and output buffers.
 295     static void flush(long connectionId, FlushCallback callback);
 296
 297     // Retrieves the state of control signals on a given connection.
 298     // |connectionId| : The id of the connection.
 299     // |callback| : Called when the control signals are available.
 300     static void getControlSignals(long connectionId,
 301                                   GetControlSignalsCallback callback);
 302
 303     // Sets the state of control signals on a given connection.
 304     // |connectionId| : The id of the connection.
 305     // |signals| : The set of signal changes to send to the device.
 306     // |callback| : Called once the control signals have been set.
 307     static void setControlSignals(long connectionId,
 308                                   HostControlSignals signals,
 309                                   SetControlSignalsCallback callback);
 310   };
 311
 312   interface Events {
 313     // Event raised when data has been read from the connection.
 314     // |info| : Event data.
 315     static void onReceive(ReceiveInfo info);
 316
 317     // Event raised when an error occurred while the runtime was waiting for
 318     // data on the serial port. Once this event is raised, the connection may be
 319     // set to <code>paused</code>. A <code>"timeout"</code> error does not pause
 320     // the connection.
 321     static void onReceiveError(ReceiveErrorInfo info);
 322   };
 323 };