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   callback GetPortsCallback = void (DOMString[] ports);
  10
  11   enum DataBit { sevenbit, eightbit };
  12   enum ParityBit { noparity, oddparity, evenparity };
  13   enum StopBit { onestopbit, twostopbit };
  14
  15   dictionary OpenOptions {
  16     // The requested bitrate of the connection to be opened. For compatibility
  17     // with the widest range of hardware, this number should match one of
  18     // commonly-available bitrates, such as 110, 300, 1200, 2400, 4800, 9600,
  19     // 14400, 19200, 38400, 57600, 115200. There is no guarantee, of course,
  20     // that the device connected to the serial port will support the requested
  21     // bitrate, even if the port itself supports that bitrate. <code>9600</code>
  22     // will be passed by default.
  23     long? bitrate;
  24     // <code>"eightbit"</code> will be passed by default.
  25     DataBit? dataBit;
  26     // <code>"noparity"</code> will be passed by default.
  27     ParityBit? parityBit;
  28     // <code>"onestopbit"</code> will be passed by default.
  29     StopBit? stopBit;
  30   };
  31
  32   dictionary OpenInfo {
  33     // The id of the opened connection.
  34     long connectionId;
  35   };
  36
  37   callback OpenCallback = void (OpenInfo openInfo);
  38
  39   // Returns true if operation was successful.
  40   callback CloseCallback = void (boolean result);
  41
  42   dictionary ReadInfo {
  43     // The number of bytes received, or a negative number if an error occurred.
  44     // This number will be smaller than the number of bytes requested in the
  45     // original read call if the call would need to block to read that number
  46     // of bytes.
  47     long bytesRead;
  48
  49     // The data received.
  50     ArrayBuffer data;
  51   };
  52
  53   callback ReadCallback = void (ReadInfo readInfo);
  54
  55   dictionary WriteInfo {
  56     // The number of bytes written.
  57     long bytesWritten;
  58   };
  59
  60   callback WriteCallback = void (WriteInfo writeInfo);
  61
  62   // Returns true if operation was successful.
  63   callback FlushCallback = void (boolean result);
  64
  65   // Boolean true = mark signal (negative serial voltage).
  66   // Boolean false = space signal (positive serial voltage).
  67   //
  68   // For SetControlSignals, include the sendable signals that you wish to
  69   // change. Signals not included in the dictionary will be left unchanged.
  70   //
  71   // GetControlSignals includes all receivable signals.
  72   dictionary ControlSignalOptions {
  73     // Serial control signals that your machine can send. Missing fields will
  74     // be set to false.
  75     boolean? dtr;
  76     boolean? rts;
  77
  78     // Serial control signals that your machine can receive. If a get operation
  79     // fails, success will be false, and these fields will be absent.
  80     //
  81     // DCD (Data Carrier Detect) is equivalent to RLSD (Receive Line Signal
  82     // Detect) on some platforms.
  83     boolean? dcd;
  84     boolean? cts;
  85   };
  86
  87   // Returns a snapshot of current control signals.
  88   callback GetControlSignalsCallback = void (ControlSignalOptions options);
  89
  90   // Returns true if operation was successful.
  91   callback SetControlSignalsCallback = void (boolean result);
  92
  93   interface Functions {
  94     // Returns names of valid ports on this machine, each of which is likely to
  95     // be valid to pass as the port argument to open(). The list is regenerated
  96     // each time this method is called, as port validity is dynamic.
  97     //
  98     // |callback| : Called with the list of ports.
  99     static void getPorts(GetPortsCallback callback);
 100
 101     // Opens a connection to the given serial port.
 102     // |port| : The name of the serial port to open.
 103     // |options| : Connection options.
 104     // |callback| : Called when the connection has been opened.
 105     static void open(DOMString port,
 106                      optional OpenOptions options,
 107                      OpenCallback callback);
 108
 109     // Closes an open connection.
 110     // |connectionId| : The id of the opened connection.
 111     // |callback| : Called when the connection has been closed.
 112     static void close(long connectionId,
 113                       CloseCallback callback);
 114
 115     // Reads a byte from the given connection.
 116     // |connectionId| : The id of the connection.
 117     // |bytesToRead| : The number of bytes to read.
 118     // |callback| : Called when all the requested bytes have been read or
 119     //              when the read blocks.
 120     static void read(long connectionId,
 121                      long bytesToRead,
 122                      ReadCallback callback);
 123
 124     // Writes a string to the given connection.
 125     // |connectionId| : The id of the connection.
 126     // |data| : The string to write.
 127     // |callback| : Called when the string has been written.
 128     static void write(long connectionId,
 129                       ArrayBuffer data,
 130                       WriteCallback callback);
 131
 132     // Flushes all bytes in the given connection's input and output buffers.
 133     // |connectionId| : The id of the connection.
 134     // |callback| : Called when the flush is complete.
 135     static void flush(long connectionId,
 136                       FlushCallback callback);
 137
 138     static void getControlSignals(long connectionId,
 139                                   GetControlSignalsCallback callback);
 140
 141     static void setControlSignals(long connectionId,
 142                                   ControlSignalOptions options,
 143                                   SetControlSignalsCallback callback);
 144   };
 145
 146 };