// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

namespace serial {

  callback GetPortsCallback = void (DOMString[] ports);

  dictionary OpenOptions {
    // The requested bitrate of the connection to be opened. For compatibility
    // with the widest range of hardware, this number should match one of
    // commonly-available bitrates, such as 110, 300, 1200, 2400, 4800, 9600,
    // 14400, 19200, 38400, 57600, 115200. There is no guarantee, of course,
    // that the device connected to the serial port will support the requested
    // bitrate, even if the port itself supports that bitrate.
    long bitrate;
  };

  dictionary OpenInfo {
    // The id of the opened connection.
    long connectionId;
  };

  callback OpenCallback = void (OpenInfo openInfo);

  // Returns true if operation was successful.
  callback CloseCallback = void (boolean result);

  dictionary ReadInfo {
    // The number of bytes received, or a negative number if an error occurred.
    // This number will be smaller than the number of bytes requested in the
    // original read call if the call would need to block to read that number
    // of bytes.
    long bytesRead;

    // The data received.
    ArrayBuffer data;
  };

  callback ReadCallback = void (ReadInfo readInfo);

  dictionary WriteInfo {
    // The number of bytes written.
    long bytesWritten;
  };

  callback WriteCallback = void (WriteInfo writeInfo);

  // Returns true if operation was successful.
  callback FlushCallback = void (boolean result);

  // Boolean true = mark signal (negative serial voltage).
  // Boolean false = space signal (positive serial voltage).
  //
  // For SetControlSignals, include the sendable signals that you wish to
  // change. Signals not included in the dictionary will be left unchanged.
  //
  // GetControlSignals includes all receivable signals.
  dictionary ControlSignalOptions {
    // Serial control signals that your machine can send. Missing fields will
    // be set to false.
    boolean? dtr;
    boolean? rts;

    // Serial control signals that your machine can receive. If a get operation
    // fails, success will be false, and these fields will be absent.
    //
    // DCD (Data Carrier Detect) is equivalent to RLSD (Receive Line Signal
    // Detect) on some platforms.
    boolean? dcd;
    boolean? cts;
  };

  // Returns a snapshot of current control signals.
  callback GetControlSignalsCallback = void (ControlSignalOptions options);

  // Returns true if operation was successful.
  callback SetControlSignalsCallback = void (boolean result);

  interface Functions {
    // Returns names of valid ports on this machine, each of which is likely to
    // be valid to pass as the port argument to open(). The list is regenerated
    // each time this method is called, as port validity is dynamic.
    //
    // |callback| : Called with the list of ports.
    static void getPorts(GetPortsCallback callback);

    // Opens a connection to the given serial port.
    // |port| : The name of the serial port to open.
    // |options| : Connection options.
    // |callback| : Called when the connection has been opened.
    static void open(DOMString port,
                     optional OpenOptions options,
                     OpenCallback callback);

    // Closes an open connection.
    // |connectionId| : The id of the opened connection.
    // |callback| : Called when the connection has been closed.
    static void close(long connectionId,
                      CloseCallback callback);

    // Reads a byte from the given connection.
    // |connectionId| : The id of the connection.
    // |bytesToRead| : The number of bytes to read.
    // |callback| : Called when all the requested bytes have been read or
    //              when the read blocks.
    static void read(long connectionId,
                     long bytesToRead,
                     ReadCallback callback);

    // Writes a string to the given connection.
    // |connectionId| : The id of the connection.
    // |data| : The string to write.
    // |callback| : Called when the string has been written.
    static void write(long connectionId,
                      ArrayBuffer data,
                      WriteCallback callback);

    // Flushes all bytes in the given connection's input and output buffers.
    // |connectionId| : The id of the connection.
    // |callback| : Called when the flush is complete.
    static void flush(long connectionId,
                      FlushCallback callback);

    static void getControlSignals(long connectionId,
                                  GetControlSignalsCallback callback);

    static void setControlSignals(long connectionId,
                                  ControlSignalOptions options,
                                  SetControlSignalsCallback callback);
  };

};