// Copyright 2016 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.

// The <code>chrome.clipboard</code> API is provided to allow users to
// access data of the clipboard. This is a temporary solution for
// chromeos platform apps until open-web alternative is available. It will be
// deprecated once open-web solution is available, which could be in 2017 Q4.
[platforms=("chromeos"),
 implemented_in="extensions/browser/api/clipboard/clipboard_api.h"]
namespace clipboard {
  // Supported image types.
  enum ImageType {png, jpeg};
  
  enum DataItemType {textPlain, textHtml};
  
  // Additional data item to be added along with the |image_data| to describe
  // the |image_data|.
  dictionary AdditionalDataItem {
    // Type of the additional data item.
    DataItemType type;

    // Content of the additional data item. Either the plain text string if
    // |type| is "textPlain" or markup string if |type| is "textHtml". The
    // data can not exceed 2MB.
    DOMString data;
  };
  
  interface Events {
    // Fired when clipboard data changes.
    // Requires clipboard and clipboardRead permissions for adding listener to
    // chrome.clipboard.onClipboardDataChanged event.
    // After this event fires, the clipboard data is available by calling
    // document.execCommand('paste').
    static void onClipboardDataChanged();
  };

  callback SetImageDataCallback = void();

  interface Functions {
    // Sets image data to clipboard.
    //
    // |imageData|: The encoded image data.
    // |type|: The type of image being passed.
    // |additionalItems|: Additional data items for describing image data.
    // The callback is called with <code>chrome.runtime.lastError</code>
    // set to error code if there is an error.
    // Requires clipboard and clipboardWrite permissions.
    static void setImageData(ArrayBuffer imageData,
                             ImageType type,
                             optional AdditionalDataItem[] additionalItems,
                             optional SetImageDataCallback callback);
  };
};