From 06fb4dbdc49446246290d195939ac4bd029be266 Mon Sep 17 00:00:00 2001 From: "benjamin%smedbergs.us" Date: Tue, 18 Jul 2006 17:36:52 +0000 Subject: [PATCH] Bug 324553, r=bryner. Finish remote container API plus manay misc fixes and cleanup. This file was copied in CVS from the following location: mozilla/browser/components/places/public/nsIRemoteContainer.idl Original committer: brettw%gmail.com Original revision: 1.1 Original date: 2006/01/26 20:24:24 --- .../places/public/nsIRemoteContainer.idl | 141 ++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 toolkit/components/places/public/nsIRemoteContainer.idl diff --git a/toolkit/components/places/public/nsIRemoteContainer.idl b/toolkit/components/places/public/nsIRemoteContainer.idl new file mode 100644 index 00000000000..9a7d1698634 --- /dev/null +++ b/toolkit/components/places/public/nsIRemoteContainer.idl @@ -0,0 +1,141 @@ +/* -*- 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 + * Google Inc. + * Portions created by the Initial Developer are Copyright (C) 2005 + * the Initial Developer. All Rights Reserved. + * + * Contributor(s): + * Annie Sullivan (original author) + * + * 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" + +interface nsIURI; +interface nsINavHistoryContainerResultNode; +interface nsINavHistoryQueryOptions; + +/** + * The Remote Container interface provides a base class for services that want + * to provide containers for bookmarks. Some examples of possible services are + * the livemarks service and the filesystem. + * + * There are two primary modes of operation: container services might create + * actual bookmarks, or they might fill containers on the fly as needed. The + * livemarks service, for example, queries the feed from time to time and + * creates actual bookmarks in the folder corresponding to the feed. This way + * the items are persistent even if the user is offline, and can be searched. + * In this mode, the service just looks for moves and deletes to update the + * corresponding bookkeeping information. It can use the normal population + * method provided by the bookmark service and need not do any work for the + * onContainerOpen message. + * + * Such a bookmark-based container service might listen for onContainerOpening + * notifications messages to see whether + + * + * Persistent bookmarks are not appropriate for more short-lived data, such as + * the filesystem interface. In this case, the service can fill result nodes + * directly into the container when it is being opened. It can use the property + * bag on every result node to store data associated with each item, such as + * full path on disk. It would create additional containers for each folder, + * resgistered to its service. These dynamic containers are not bookmark + * folders in contrast to the initial item. + */ + +[scriptable, uuid(45bf2020-9683-498c-9638-f08130c4151d)] +interface nsIRemoteContainer : nsISupports +{ + + /** + * Called when the given container is about to be populated so that the + * service can populate the container if necessary. + * + * @param container The container node for the container being opened. + * If the node type is a bookmarks container, you can + * QI it to nsINavHistoryFolderResultNode and access the + * folder ID, etc. Note that all result nodes implement + * a property bag if you need to store state. + * @param options The options used to generate this query. Containers + * should follow these when possible, for example, + * whether to expand queries, etc. Implementations should + * use this when possible if adding query and folder nodes + * to the container. DO NOT MODIFY THIS VALUE. + */ + void onContainerOpening(in nsINavHistoryContainerResultNode container, + in nsINavHistoryQueryOptions options); + + /** + * Called when the given container has just been hidden so that the service + * can do any necessary cleanup. This is NOT guaranteed to get called. In + * particular, if the query just goes away (like the user switched views on + * the places page) you will not get this call. This only happens when the + * container itself goes from the open state to the closed state. A serviced + * with large numbers of dynamically populated items might use this to do + * some cleanup so those items don't hang around + * + * @param container The container node of the container being closed. The + * service need not worry about removing any created nodes, + * they will be automatically removed when this call + * completes. + */ + void onContainerClosed(in nsINavHistoryContainerResultNode container); + + /** + * Called when the given container is about to be deleted, so + * that the service can do any necessary cleanup. + * Called BEFORE the container is deleted, so that the service + * can still reference it. + * @param container The folderId of the bookmark folder + * representing the container to be deleted. + */ + void onContainerRemoving(in PRInt64 container); + + /** + * Called when the given container has just been moved, in case + * the service needs to do any bookkeeping. + * Called AFTER the container has been moved, so the service can + * get the new URI. + * @param container The folderId of the bookmark folder + * representing the container to be moved. + * @param newFolder The folderId of the new parent folder + * for the container. + * @param newIndex The index the container will be inserted at, + * or -1 for append. + */ + void onContainerMoved(in PRInt64 container, + in PRInt64 newFolder, in PRInt32 newIndex); + + /** + * Returns true if containers of this type should not expose UI for + * inserting, moving, or deleting children. + */ + readonly attribute boolean childrenReadOnly; +};