michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIURI;
michael@0: interface nsIVariant;
michael@0: 
michael@0: [scriptable, uuid(f816b4df-f733-4dbd-964d-8bfc92a475b2)]
michael@0: interface nsITaggingService : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Tags a URL with the given set of tags. Current tags set for the URL
michael@0:    * persist. Tags in aTags which are already set for the given URL are
michael@0:    * ignored.
michael@0:    *
michael@0:    * @param aURI
michael@0:    *        the URL to tag.
michael@0:    * @param aTags
michael@0:    *        Array of tags to set for the given URL.  Each element within the
michael@0:    *        array can be either a tag name (non-empty string) or a concrete
michael@0:    *        itemId of a tag container.
michael@0:    */
michael@0:   void tagURI(in nsIURI aURI, in nsIVariant aTags);
michael@0: 
michael@0:   /**
michael@0:    * Removes tags from a URL. Tags from aTags which are not set for the
michael@0:    * given URL are ignored.
michael@0:    *
michael@0:    * @param aURI
michael@0:    *        the URL to un-tag.
michael@0:    * @param aTags
michael@0:    *        Array of tags to unset.  Pass null to remove all tags from the given
michael@0:    *        url.  Each element within the array can be either a tag name
michael@0:    *        (non-empty string) or a concrete itemId of a tag container.
michael@0:    */
michael@0:   void untagURI(in nsIURI aURI, in nsIVariant aTags);
michael@0: 
michael@0:   /**
michael@0:    * Retrieves all URLs tagged with the given tag.
michael@0:    *
michael@0:    * @param aTag
michael@0:    *        tag name
michael@0:    * @returns Array of uris tagged with aTag.
michael@0:    */
michael@0:   nsIVariant getURIsForTag(in AString aTag);
michael@0: 
michael@0:   /**
michael@0:    * Retrieves all tags set for the given URL.
michael@0:    *
michael@0:    * @param aURI
michael@0:    *        a URL.
michael@0:    * @returns array of tags (sorted by name).
michael@0:    */
michael@0:   void getTagsForURI(in nsIURI aURI,
michael@0:                      [optional] out unsigned long length,
michael@0:                      [retval, array, size_is(length)] out wstring aTags);
michael@0: 
michael@0:   /**
michael@0:    * Retrieves all tags used to tag URIs in the data-base (sorted by name).
michael@0:    */
michael@0:   readonly attribute nsIVariant allTags;
michael@0: 
michael@0:   /**
michael@0:    * Whether any tags exist.
michael@0:    *
michael@0:    * @note This is faster than allTags.length, since doesn't need to sort tags.
michael@0:    */
michael@0:   readonly attribute boolean hasTags;
michael@0: };
michael@0: 
michael@0: %{C++
michael@0: 
michael@0: #define TAGGING_SERVICE_CID "@mozilla.org/browser/tagging-service;1"
michael@0: 
michael@0: %}