gecko/browser/components/places/public/nsIPlacesTransactionsService.idl

/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is Places.
 *
 * The Initial Developer of the Original Code is Mozilla Foundation
 *
 * Portions created by the Initial Developer are Copyright (C) 2007
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Sungjoon Steve Won <stevewon@gmail.com> (Original Author)
 *   Asaf Romano <mano@mozilla.com>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"
#include "nsITransactionManager.idl"

interface nsIVariant;
interface nsIURI;
interface nsIMicrosummary;
interface nsITransaction;

/**
 * nsIPlacesTransactionService is a service designed to handle
 * nsITransactions that correspond to changes in Places. It is here as a
 * service so that we can keep the transactions around without holding onto
 * the global scope of a js window.
 *
 * NOTE: If you are interacting directly with the Places back-end, and you
 *       need to transactionalize a large amount of changes, look at
 *       nsINavBookmarksService.runInBatchMode.
 */

[scriptable, uuid(32eee5da-2bc7-4d18-8a54-a8ff0dec4d2a)]
interface nsIPlacesTransactionsService : nsITransactionManager
{
  /**
   * Transaction for performing several Places Transactions in a single batch. 
   * 
   * @param aName
   *        title of the aggregate transactions
   * @param aTransactions
   *        an array of transactions to perform
   * @returns nsITransaction object
   */
  nsITransaction aggregateTransactions(in AString aName,
                                       in nsIVariant aTransactions);

  /**
   * Transaction for creating a new folder item.
   *
   * @param aName
   *        the name of the new folder
   * @param aContainerId
   *        the identifier of the folder in which the new folder should be
   *        added.
   * @param [optional] aIndex
   *        the index of the item in aContainer, pass -1 or nothing to create
   *        the item at the end of aContainer.
   * @param [optional] aAnnotations
   *        the annotations to set for the new folder.
   * @param [optional] aChildItemsTransactions
   *        array of transactions for items to be created under the new folder.
   * @returns nsITransaction object
   */
  nsITransaction createFolder(in AString aName, in long long aContainerId,
                              [optional] in long long aIndex,
                              [optional] in nsIVariant aAnnotations,
                              [optional] in nsIVariant aChildItemsTransactions);

  /**
   * Transaction for creating a new bookmark item
   *
   * @param aURI
   *        the uri of the new bookmark (nsIURI)
   * @param aContainerId
   *        the identifier of the folder in which the bookmark should be added.
   * @param [optional] aIndex
   *        the index of the item in aContainer, pass -1 or nothing to create
   *        the item at the end of aContainer.
   * @param [optional] aTitle
   *        the title of the new bookmark.
   * @param [optional] aKeyword
   *        the keyword of the new bookmark.
   * @param [optional] aAnnotations
   *        the annotations to set for the new bookmark.
   * @param [optional] aChildTransactions
   *        child transactions to commit after creating the bookmark. Prefer
   *        using any of the arguments above if possible. In general, a child
   *        transations should be used only if the change it does has to be
   *        reverted manually when removing the bookmark item.
   *        a child transaction must support setting its bookmark-item
   *        identifier via an "id" js setter.
   * @returns nsITransaction object
   */
  nsITransaction createItem(in nsIURI aURI, in long long aContainerId,
                            [optional] in long long aIndex,
                            [optional] in AString aTitle,
                            [optional] in AString aKeyword,
                            [optional] in nsIVariant aAnnotations,
                            [optional] in nsIVariant aChildTransactions);

  /**
   * Transaction for creating a new separator item
   *
   * @param aContainerId
   *        the identifier of the folder in which the separator should be
   *        added.
   * @param [optional] aIndex
   *        the index of the item in aContainer, pass -1 or nothing to create
   *        the separator at the end of aContainer.
   * @returns nsITransaction object
   */
  nsITransaction createSeparator(in long long aContainerId,
                                 [optional] in long long aIndex);

  /**
   * Transaction for creating a new live-bookmark item.
   *
   * @see nsILivemarksService::createLivemark for documentation regarding the
   * first three arguments.
   *
   * @param aContainerId
   *        the identifier of the folder in which the live-bookmark should be
   *        added.
   * @param [optional]  aIndex
   *        the index of the item in aContainer, pass -1 or nothing to create
   *        the item at the end of aContainer.
   * @param [optional] aAnnotations
   *        the annotations to set for the new live-bookmark.
   * @returns nsITransaction object
   */
  nsITransaction createLivemark(in nsIURI aFeedURI,
                                in nsIURI aSiteURI,
                                in AString aName,
                                in long long aContainerId,
                                [optional] in long long aIndex,
                                [optional] in nsIVariant aAnnotations);

  /**
   * Transaction for moving an Item.
   *
   * @param aItemId
   *        the id of the item to move
   * @param aNewContainerId
   *        id of the new container to move to
   * @param aNewIndex
   *        index of the new position to move to
   * @returns nsITransaction object
   */
  nsITransaction moveItem(in long long aItemId,
                          in long long aNewContainerId,
                          in long long aNewIndex);

  /**
   * Transaction for removing an Item
   *
   * @param aItemId
   *        id of the item to remove
   * @returns nsITransaction object
   */
  nsITransaction removeItem(in long long aItemId);

  /**
   * Transaction for editting a bookmark's title.
   *
   * @param aItemId
   *        id of the item to edit
   * @param aNewTitle
   *        new title for the item to edit
   * @returns nsITransaction object
   */
  nsITransaction editItemTitle(in long long aItemId, in AString aNewTitle);

  /**
   * Transaction for editing a bookmark's uri.
   *
   * @param aBookmarkId
   *        id of the bookmark to edit
   * @param aNewURI
   *        new uri for the bookmark
   * @returns nsITransaction object
   */
  nsITransaction editBookmarkURI(in long long aBookmarkId, in nsIURI aNewURI);

  /**
   * Transaction for setting/unsetting an item annotation
   *
   * @param aItemId
   *        id of the item where to set annotation
   * @param aAnnotationObject
   *        Object representing an annotation, containing the following
   *        properties: name, flags, expires, type, mimeType (only used for
   *        binary annotations), value.
   *        If value is null the annotation will be removed
   * @returns nsITransaction object
   */
  nsITransaction setItemAnnotation(in nsIVariant aItemId,
                                   in nsIVariant aAnnotationObject);

  /**
   * Transaction for setting/unsetting a page annotation
   *
   * @param aURI
   *        URI of the page where to set annotation
   * @param aAnnotationObject
   *        Object representing an annotation, containing the following
   *        properties: name, flags, expires, type, mimeType (only used for
   *        binary annotations), value.
   *        If value is null the annotation will be removed
   * @returns nsITransaction object
   */
  nsITransaction setPageAnnotation(in nsIURI aURI,
                                   in nsIVariant aAnnotationObject);

  /**
   * Transaction for setting/unsetting Load-in-sidebar annotation
   *
   * @param aBookmarkId
   *        id of the bookmark where to set Load-in-sidebar annotation
   * @param aLoadInSidebar
   *        boolean value
   * @returns nsITransaction object
   */
  nsITransaction setLoadInSidebar(in long long aBookmarkId,
                                  in boolean aLoadInSidebar);

  /**
   * Transaction for editing a the description of a bookmark or a folder
   * 
   * @param aItemId
   *        id of the item to edit
   * @param aDescription
   *        new description
   * @returns nsITransaction object
   */
  nsITransaction editItemDescription(in long long aItemId,
                                     in AString aDescription);

  /**
   * Transaction for editing a bookmark's keyword.
   *
   * @param aBookmarkId
   *        id of the bookmark to edit
   * @param aNewKeyword
   *        new keyword for the bookmark
   * @returns nsITransaction object
   */
  nsITransaction editBookmarkKeyword(in long long aBookmarkId,
                                     in AString aNewKeyword);

  /**
   * Transaction for editing the post data associated with a bookmark.
   *
   * @param aBookmarkId
   *        id of the bookmark to edit
   * @param aPostData
   *        post data
   * @returns nsITransaction object
   */
  nsITransaction editBookmarkPostData(in long long aBookmarkId,
                                      in AString aPostData);

  /**
   * Transaction for editing a live bookmark's site URI.
   *
   * @param aLivemarkId
   *        id of the livemark
   * @param aURI
   *        new site uri
   * @returns nsITransaction object
   */
  nsITransaction editLivemarkSiteURI(in long long aLivemarkId, in nsIURI aURI);

  /**
   * Transaction for editting a live bookmark's feed URI.
   *
   * @param aLivemarkId
   *        id of the livemark
   * @param aURI
   *        new feed uri
   * @returns nsITransaction object
   */
  nsITransaction editLivemarkFeedURI(in long long aLivemarkId, in nsIURI aURI);

  /**
   * Transaction for editing a bookmark's microsummary.
   *
   * @param aBookmarkId
   *        id of the bookmark to edit
   * @param aNewMicrosummary
   *        new microsummary for the bookmark
   * @returns nsITransaction object
   */
  nsITransaction editBookmarkMicrosummary(in long long aBookmarkId,
                                          in nsIMicrosummary aNewMicrosummary);

  /**
   * Transaction for editing an item's date added property.
   *
   * @param aItemId
   *        id of the item to edit
   * @param aNewDateAdded
   *        new date added for the item 
   * @returns nsITransaction object
   */
  nsITransaction editItemDateAdded(in long long aItemId,
                                   in PRTime aNewDateAdded);

  /**
   * Transaction for editing an item's last modified time.
   *
   * @param aItemId
   *        id of the item to edit
   * @param aNewLastModified
   *        new last modified date for the item 
   * @returns nsITransaction object
   */
  nsITransaction editItemLastModified(in long long aItemId,
                                      in PRTime aNewLastModified);

  /**
   * Transaction for sorting a folder by name
   *
   * @param aFolderId
   *        id of the folder to sort
   * @returns nsITransaction object
   */
  nsITransaction sortFolderByName(in long long aFolderId);

  /**
   * Transaction for tagging a URL with the given set of tags. Current tags set
   * for the URL persist. It's the caller's job to check whether or not aURI
   * was already tagged by any of the tags in aTags, undoing this tags
   * transaction removes them all from aURL!
   *
   * @param aURI
   *        the URL to tag.
   * @param aTags
   *        Array of tags to set for the given URL.
   */
  nsITransaction tagURI(in nsIURI aURI, in nsIVariant aTags);

  /**
   * Transaction for removing tags from a URL. It's the caller's job to check
   * whether or not aURI isn't tagged by any of the tags in aTags, undoing this
   * tags transaction adds them all to aURL!
   *
   * @param aURI
   *        the URL to un-tag.
   * @param aTags
   *        Array of tags to unset. pass null to remove all tags from the given
   *        url.
   */
  nsITransaction untagURI(in nsIURI aURI, in nsIVariant aTags);
};