/* 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 nsIMsgFolder;

[scriptable, builtinclass, uuid(2842d879-e52f-4812-926c-dfde62b77881)]
interface nsIFolderDatabase : nsISupports {
  /**
   * Get a folder identified by its path.
   * If individual folder names contain '/', it should be
   * percent-encoded when used in a path.
   * e.g. a folder called "I/O Stuff", would appear in a path like:
   *   "server1/I%2FO Stuff/gpio"
   *
   * The search is unicode-aware, so the following paths
   * are considered equivalent:
   *  "server2/stuff/süb1"
   *  "server2/stuff/s\u00FCb1"
   *  "server2/stuff/su\u0308b1"
   *
   * If the path does not exist, a folder id of 0 will be returned.
   */
  unsigned long long getFolderByPath(in AUTF8String path);

  /**
   * For a given folder id, return the corresponding nsIMsgFolder.
   *
   * NOTE: (BenC) I'd like to move this method out of this interface,
   * maybe into accountmanager instead.
   * It's the only thing that couples FolderDatabase to nsIMsgFolder.
   *
   * Throws an error if `folder` is 0 or does not exist.
   */
  nsIMsgFolder getMsgFolderForFolder(in unsigned long long folder);

  /**
   * Add and return a new root folder representing a server to the database.
   *
   * This function will be called on initial database creation and when a new
   * incoming server is created.
   *
   * An error will be thrown if the folder already exists.
   */
  unsigned long long insertRoot(in AUTF8String aServerKey);

  /**
   * Add a folder named `name` to the database as a child of `parent`.
   *
   * This function should be called by the protocol code after the folder is
   * created on the server. The parent folder is not optional.
   *
   * An error will be thrown if the folder already exists.
   */
  unsigned long long insertFolder(in unsigned long long parent,
                                  in AUTF8String name);

  /**
   * Delete `folder` and all of its descendants from the database.
   *
   * This function should be called by the protocol code after the folder is
   * deleted on the server. Deleting a root folder with this function is not
   * permitted.
   */
  void deleteFolder(in unsigned long long folder);

  /**
   * Update the children of `parent` to match the child names expected. If a
   * name is in `childNames` but no child exists, it will be created. If a
   * child exists but its name is not in `childNames`, it and all of its
   * descendants are removed from the database.
   *
   * This function should be called by the protocol code after collecting the
   * child names from the server.
   */
  void reconcile(in unsigned long long parent,
                 in Array<AUTF8String> childNames);

  /**
   * Move a folder to a different position among its siblings. Yes, passing in
   * the parent folder is redundant here, but it makes reading the code easier.
   *
   * This function should be called by the UI, nothing else is affected.
   * If `before` is 0 or missing, the child will be moved to the end of the
   * child list.
   */
  void moveFolderWithin(in unsigned long long parent,
                        in unsigned long long child,
                        [optional] in unsigned long long before);

  /**
   * Reset a folders children into their natural order.
   *
   * This function should be called by the UI, nothing else is affected.
   */
  void resetChildOrder(in unsigned long long parent);

  /**
   * Move a folder from one parent to another.
   * Folders cannot be:
   * - made descendants of themselves.
   * - promoted to root folders.
   * - moved from one server (root) to another
   * (Although the last restriction could potentially be lifted in future)
   */
  void moveFolderTo(in unsigned long long newParent,
                    in unsigned long long child);

  /**
   * Update a folder's name to match `newName`.
   */
  void updateName(in unsigned long long folder, in AUTF8String newName);

  /**
   * Update a folder's flags to match `newFlags`.
   */
  void updateFlags(in unsigned long long folder, in unsigned long long newFlags);

  /**
   * Returns the name of a folder.
   * Throws an error if folder doesn't exist.
   */
  AUTF8String getFolderName(in unsigned long long folderId);

  /**
   * Returns the path of a folder, up to and including the server (root
   * folder).
   * The path separator is '/'.
   * Any '/' characters in folder names will be percent-encoded in the path.
   *
   * Throws an error if folder doesn't exist.
   */
  AUTF8String getFolderPath(in unsigned long long folderId);

  /**
   * Returns the flags of a folder.
   * Throws an error if folder doesn't exist.
   */
  uint32_t getFolderFlags(in unsigned long long folderId);

  /**
   * Returns true if the folder is a server (i.e. root folder).
   * Equivalent to checking if parent folder is 0.
   * Throws an error if folder doesn't exist.
   */
  boolean getFolderIsServer(in unsigned long long folderId);

  /**
   * Return the parent of the specified folder.
   * Root folders always have parent 0.
   * Throws an error if folder doesn't exist.
   */
  unsigned long long getFolderParent(in unsigned long long folderId);

  /**
   * Fetch a list of child folders.
   * `folderId` can be 0 to fetch a list of root folders.
   *
   * The returned list is ordered according to the folder sorting policy.
   *
   * Throws an error if folder doesn't exist (and isn't 0).
   */
  Array<unsigned long long> getFolderChildren(in unsigned long long folderId);

  /**
   * Find the child of `folderId` named `childName`.
   * `folderId` may be 0 to search root folders.
   * If the folder is not found, the method will succeed and 0 will be
   * returned.
   */
  unsigned long long getFolderChildNamed(in unsigned long long folderId,
                                         in AUTF8String childName);

  /**
   * Fetch the root folder of `folderId`.
   * Root folders have themselves as root.
   *
   * Throws an error if called for 0 or non-existent folder.
   */
  unsigned long long getFolderRoot(in unsigned long long folderId);

  /**
   * Return a list of all the descendants of the folder.
   * It can be called with folder 0 to return _all_ folders.
   * The ordering is the same as you'd expect from a standard tree view,
   * a depth-first traversal with siblings ordered using the folder sorting
   * policy.
   * For example, with the following tree:
   *
   *   a
   *     aa
   *       aaa
   *       aab
   *   b
   *     ba
   *     bb
   *
   * getFolderDescendants(a) would return [aa, aaa, aab]
   * getFolderDescendants(0) would return [a, aa, aaa, aab, b, ba, bb]
   * getFolderDescendants(ba) would return []
   * etc...
   */
  Array<unsigned long long> getFolderDescendants(in unsigned long long folderId);

  /**
   * Return ancestor folders, all the way up to (and including) the root.
   * The returned list is ordered by decreasing depth. So for the tree:
   *
   *  root
   *    foo
   *      bar
   * getFolderAncestors(bar) would return [foo, root]
   * getFolderAncestors(foo) would return [root]
   * getFolderAncestors(root) would return []
   *
   * Throws an error if called for 0 or non-existent folder.
   */
  Array<unsigned long long> getFolderAncestors(in unsigned long long folderId);

  /**
   * Returns true if `folderId` is a descendant of `potentialAncestorId`.
   *
   * Throws an error if either folder is non-existent.
   */
  boolean getFolderIsDescendantOf(in unsigned long long folderId,
                                  in unsigned long long potentialAncestorId);

  /**
   * Returns true if `folderId` is an ancestor of `potentialDescendantId`.
   *
   * Throws an error if either folder is non-existent.
   */
  boolean getFolderIsAncestorOf(in unsigned long long folderId,
                                in unsigned long long potentialDescendantId);
};