/* -*- 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 (Original Author) * Asaf Romano * * 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); };