toolkit/components/places/public/nsILivemarkService.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is Places code
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Google Inc.
  19  * Portions created by the Initial Developer are Copyright (C) 2005
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   Annie Sullivan <annie.sullivan@gmail.com>
  24  *   Joe Hughes <joe@retrovirus.com>
  25  *   Takeshi Ichimaru <ayakawa.m@gmail.com>
  26  *
  27  * Alternatively, the contents of this file may be used under the terms of
  28  * either the GNU General Public License Version 2 or later (the "GPL"), or
  29  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30  * in which case the provisions of the GPL or the LGPL are applicable instead
  31  * of those above. If you wish to allow use of your version of this file only
  32  * under the terms of either the GPL or the LGPL, and not to allow others to
  33  * use your version of this file under the terms of the MPL, indicate your
  34  * decision by deleting the provisions above and replace them with the notice
  35  * and other provisions required by the GPL or the LGPL. If you do not delete
  36  * the provisions above, a recipient may use your version of this file under
  37  * the terms of any one of the MPL, the GPL or the LGPL.
  38  *
  39  * ***** END LICENSE BLOCK ***** */
  40
  41 #include "nsISupports.idl"
  42
  43 interface nsIURI;
  44 interface nsINavBookmarksService;
  45
  46 [scriptable, uuid(2c08ab79-7f9b-40f3-8d04-540b5857b211)]
  47 interface nsILivemarkService : nsISupports
  48 {
  49   /**
  50    * Starts the livemark refresh timer.
  51    * Being able to manually control this allows activity such
  52    * as bookmarks import to occur without kicking off HTTP traffic.
  53    */
  54   void start();
  55
  56   /**
  57    * Stop the livemark refresh timer.
  58    */
  59   void stopUpdateLivemarks();
  60
  61   /**
  62    * Creates a new livemark
  63    * @param folder      The id of the parent folder
  64    * @param name        The name to show when displaying the livemark
  65    * @param siteURI     The URI of the site the livemark was created from
  66    * @param feedURI     The URI of the actual RSS feed
  67    * @param index       The index to insert at, or -1 to append
  68    * @returns the ID of the folder for the livemark
  69    */
  70   long long createLivemark(in long long folder,
  71                            in AString name,
  72                            in nsIURI siteURI,
  73                            in nsIURI feedURI,
  74                            in long index);
  75
  76   /**
  77    * Same as above, use during startup to avoid HTTP traffic
  78    */
  79   long long createLivemarkFolderOnly(in long long folder,
  80                                      in AString name,
  81                                      in nsIURI siteURI,
  82                                      in nsIURI feedURI,
  83                                      in long index);
  84
  85   /**
  86    * Determines whether the folder with the given folder ID identifies
  87    * a livemark container.
  88    *
  89    * @param folder    A folder ID
  90    *
  91    * @returns true if the given folder is a livemark folder, or
  92    *          false otherwise
  93    *
  94    * @throws NS_ERROR_INVALID_ARG if the folder ID isn't known
  95    */
  96   boolean isLivemark(in long long folder);
  97
  98   /**
  99    * Gets the URI of the website associated with a livemark container.
 100    *
 101    * @param container  The folder ID of a livemark container
 102    *
 103    * @returns nsIURI representing the URI of the website; if the livemark
 104    *          container doesn't have a valid site URI, null will be returned
 105    *
 106    * @throws NS_ERROR_INVALID_ARG if the folder ID isn't known or identifies
 107    *         a folder that isn't a livemark container
 108    * @throws NS_ERROR_MALFORMED_URI if the site URI annotation has
 109    *         somehow been corrupted (and can't be turned into an nsIURI)
 110    */
 111   nsIURI getSiteURI(in long long container);
 112
 113   /**
 114    * Sets the URI of the website associated with a livemark container.
 115    *
 116    * @param container  The folder ID of a livemark container
 117    * @param siteURI    nsIURI object representing the site URI, or null
 118    *                   to clear the site URI for this livemark container
 119    *
 120    * @throws NS_ERROR_INVALID_ARG if the folder ID isn't known or identifies
 121    *         a folder that isn't a livemark container; also if the siteURI
 122    *         argument isn't a valid nsIURI object (or null)
 123    */
 124   void setSiteURI(in long long container, in nsIURI siteURI);
 125
 126   /**
 127    * Gets the URI of the syndication feed associated with a livemark container.
 128    *
 129    * @param container  The folder ID of a livemark container
 130    *
 131    * @returns nsIURI representing the URI of the feed; if the livemark
 132    *          container doesn't have a valid feed URI, null will be returned
 133    *          of the nsIURI object returned will be the empty string.
 134    *
 135    * @throws NS_ERROR_INVALID_ARG if the folder ID isn't known or identifies
 136    *         a folder that isn't a livemark container
 137    * @throws NS_ERROR_MALFORMED_URI if the site URI annotation has
 138    *         somehow been corrupted (and can't be turned into an nsIURI)
 139    */
 140   nsIURI getFeedURI(in long long container);
 141
 142   /**
 143    * Sets the URI of the feed associated with a livemark container.
 144    *
 145    * NOTE: The caller is responsible for reloading the livemark after
 146    *       changing its feed URI (since the contents are likely to be different
 147    *       given a different feed).
 148    *
 149    * @param container  The folder ID of a livemark container
 150    * @param feedURI    nsIURI object representing the syndication feed URI
 151    *
 152    * @throws NS_ERROR_INVALID_ARG if the folder ID isn't known or identifies
 153    *         a folder that isn't a livemark container; also if the feedURI
 154    *         argument isn't a valid nsIURI object
 155    */
 156   void setFeedURI(in long long container, in nsIURI feedURI);
 157
 158         /**
 159          * Reloads all livemark subscriptions, whether or not they've expired.
 160          */
 161   void reloadAllLivemarks();
 162
 163         /**
 164          * Reloads the livemark with this folder ID, whether or not it's expired.
 165          * @param folderID              The ID of the folder to be reloaded
 166          */
 167   void reloadLivemarkFolder(in long long folderID);
 168 };
 169
 170 %{C++
 171 #define LMANNO_FEEDURI "livemark/feedURI"
 172 %}