toolkit/components/places/nsITaggingService.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsIURI;
   9 interface nsIVariant;
  10
  11 [scriptable, uuid(9759bd0e-78e2-4421-9ed1-c676e1af3513)]
  12 interface nsITaggingService : nsISupports
  13 {
  14   /**
  15    * Tags a URL with the given set of tags. Current tags set for the URL
  16    * persist. Tags in aTags which are already set for the given URL are
  17    * ignored.
  18    *
  19    * @param aURI
  20    *        the URL to tag.
  21    * @param aTags
  22    *        Array of tags to set for the given URL.  Each element within the
  23    *        array can be either a tag name (non-empty string) or a concrete
  24    *        itemId of a tag container.
  25    * @param [optional] aSource
  26    *        A change source constant from nsINavBookmarksService::SOURCE_*.
  27    *        Defaults to SOURCE_DEFAULT if omitted.
  28    */
  29   void tagURI(in nsIURI aURI,
  30               in nsIVariant aTags,
  31               [optional] in unsigned short aSource);
  32
  33   /**
  34    * Removes tags from a URL. Tags from aTags which are not set for the
  35    * given URL are ignored.
  36    *
  37    * @param aURI
  38    *        the URL to un-tag.
  39    * @param aTags
  40    *        Array of tags to unset.  Pass null to remove all tags from the given
  41    *        url.  Each element within the array can be either a tag name
  42    *        (non-empty string) or a concrete itemId of a tag container.
  43    * @param [optional] aSource
  44    *        A change source constant from nsINavBookmarksService::SOURCE_*.
  45    *        Defaults to SOURCE_DEFAULT if omitted.
  46    */
  47   void untagURI(in nsIURI aURI,
  48                 in nsIVariant aTags,
  49                 [optional] in unsigned short aSource);
  50
  51   /**
  52    * Retrieves all tags set for the given URL.
  53    *
  54    * @param aURI
  55    *        a URL.
  56    * @returns array of tags (sorted by name).
  57    */
  58   Array<AString> getTagsForURI(in nsIURI aURI);
  59
  60 };