/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface mozIPlacesPendingOperation;
interface mozIStorageConnection;
interface nsIPropertyBag;

// A progress listener used to record telemetry.
[scriptable, uuid(6239ffe3-6ffd-49ac-8b1d-958407395bf9)]
interface mozISyncedBookmarksMirrorProgressListener : nsISupports {
  // Called after the merger fetches the local tree from Places, with the time
  // taken to build the tree, number of items in the tree, and a map of
  // structure problem counts for validation telemetry.
  void onFetchLocalTree(in long long took, in long long itemCount,
                        in long long deletedCount, in nsIPropertyBag problems);

  // Called after the merger builds the remote tree from the mirror database.
  void onFetchRemoteTree(in long long took, in long long itemCount,
                         in long long deletedCount, in nsIPropertyBag problems);

  // Called after the merger builds the merged tree, including structure change
  // counts for event telemetry.
  void onMerge(in long long took, in nsIPropertyBag counts);

  // Called after the merger finishes applying the merged tree to Places and
  // staging outgoing items.
  void onApply(in long long took);
};

// A callback called when the merge finishes.
[scriptable, uuid(d23fdfea-92c8-409d-a516-08ae395d578f)]
interface mozISyncedBookmarksMirrorCallback : nsISupports {
  void handleSuccess(in boolean result);
  void handleError(in nsresult code, in AString message);
};

[scriptable, builtinclass, uuid(f0a6217d-8344-4e68-9995-bbf5554be86e)]
interface mozISyncedBookmarksMerger : nsISupports {
  // Synced item kinds. These are stored in the mirror database.
  cenum SyncedItemKinds : 8 {
    KIND_BOOKMARK = 1,
    KIND_QUERY = 2,
    KIND_FOLDER = 3,
    KIND_LIVEMARK = 4,
    KIND_SEPARATOR = 5,
  };

  // Synced item validity states. These are also stored in the mirror
  // database. `REUPLOAD` means a remote item can be fixed up and applied,
  // and should be reuploaded. `REPLACE` means a remote item isn't valid
  // at all, and should either be replaced with a valid local copy, or deleted
  // if a valid local copy doesn't exist.
  cenum SyncedItemValidity : 8 {
    VALIDITY_VALID = 1,
    VALIDITY_REUPLOAD = 2,
    VALIDITY_REPLACE = 3,
  };

  // The mirror database connection to use for merging. The merge runs on the
  // connection's async thread, to avoid blocking the main thread. The
  // connection must be open, and the database schema, temp tables, and
  // triggers must be set up before calling `merge`.
  attribute mozIStorageConnection db;

  // Merges the local and remote bookmark trees, applies the merged tree to
  // Places, and stages locally changed and reconciled items for upload. When
  // the merge finishes, either `callback.handleSuccess` or
  // `callback.handleError` are called. If `callback` also implements
  // `mozISyncedBookmarksMergerProgressListener`, the merger reports progress
  // after each step. Returns an object with a `cancel` method that can be used
  // to interrupt the merge.
  mozIPlacesPendingOperation merge(
    in long long localTimeSeconds,
    in long long remoteTimeSeconds,
    in mozISyncedBookmarksMirrorCallback callback
  );

  // Resets the database connection. This does _not_ automatically
  // close the database connection.
  void reset();
};