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

// <p>
//   The API that can be used by an app to create and manage data on the
//   Chrome OS lock screen.
// </p>
// <p>
//   The API usability will depend on the user session state:
//   <ul>
//     <li>
//       When the user session is locked, the API usage will only be allowed
//       from the lock screen context.
//     </li>
//     <li>
//       When the user session is not locked, the API usage will only be
//       allowed outside the lock screen context - i.e. from the regular app
//       context.
//     </li>
//   </ul>
// </p>
// <p>
//   Note that apps have reduced access to Chrome apps APIs from the lock screen
//   context.
// </p>
namespace lockScreen.data {
  // The basic information about available data items originating from the lock
  // screen.
  dictionary DataItemInfo {
    // The data item ID that can later be used to retrieve and update the
    // associated lock screen data.
    DOMString id;
  };

  dictionary DataItemsAvailableEvent {
    // <p>Whether the event was dispatched as a result of the user session
    //    getting unlocked.
    //    </p>
    // <p>For example:
    //   <ul>
    //     <li>If the app creates new data items while shown on
    //         the lock screen, when the user unlocks the screen,
    //         $(ref:onDataItemsAvailable) event will be dispatched with this
    //         property set to <code>true</code>.
    //         </li>
    //     <li>When the user logs in, if not previously reported lock screen
    //         data items are found, which could happen if the user session had
    //         been closed while it was locked, $(ref:onDataItemsAvailable) will
    //         be dispatched with this property set to <code>false</code>.
    //         </li>
    //   </ul>
    // </p>
    boolean wasLocked;
  };

  callback DataItemCallback = void(DataItemInfo item);
  callback DataItemListCallback = void(DataItemInfo[] items);
  callback DataCallback = void(ArrayBuffer data);
  callback VoidCallback = void();

  interface Functions {
    // Creates a new data item reference - available only in lock screen
    // contexts.
    static void create(DataItemCallback callback);

    // Gets references to all data items available to the app.
    static void getAll(DataItemListCallback callback);

    // Retrieves content of the data item identified by |id|.
    static void getContent(DOMString id, DataCallback callback);

    // Sets contents of a data item.
    // |id| - Identifies the target data item.
    // |data| - The data item contents to set.
    static void setContent(DOMString id,
                           ArrayBuffer data,
                           optional VoidCallback callback);

    // Deletes a data item. The data item will not be available through this
    // API anymore.
    // |id| - Identifies the data item to delete.
    static void delete(DOMString id, optional VoidCallback callback);
  };

  interface Events {
    // Dispatched when new data items become available to main, non-lock screen
    // app context - this event is not expected to be dispatched to the app in
    // the lock screen context.
    static void onDataItemsAvailable(DataItemsAvailableEvent event);
  };
};