The Tor Browser: toolkit/components/places/nsIAnnotationService.idl@b8a032363ba2 (annotated)

toolkit/components/places/nsIAnnotationService.idl@b8a032363ba2 (annotated)

toolkit/components/places/nsIAnnotationService.idl

Thu, 22 Jan 2015 13:21:57 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 22 Jan 2015 13:21:57 +0100
branch: TOR_BUG_9701
changeset 15: b8a032363ba2
permissions: -rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 #include "nsISupports.idl"
 interface nsIURI;
 interface nsIVariant;
 interface mozIAnnotatedResult;
 [scriptable, uuid(63fe98e0-6889-4c2c-ac9f-703e4bc25027)]
 interface nsIAnnotationObserver : nsISupports
 {
     /**
      * Called when an annotation value is set. It could be a new annotation,
      * or it could be a new value for an existing annotation.
      */
     void onPageAnnotationSet(in nsIURI aPage,
                              in AUTF8String aName);
     void onItemAnnotationSet(in long long aItemId,
                              in AUTF8String aName);
     /**
      * Called when an annotation is deleted. If aName is empty, then ALL
      * annotations for the given URI have been deleted. This is not called when
      * annotations are expired (normally happens when the app exits).
      */
     void onPageAnnotationRemoved(in nsIURI aURI,
                                  in AUTF8String aName);
     void onItemAnnotationRemoved(in long long aItemId,
                                  in AUTF8String aName);
 };
 [scriptable, uuid(D4CDAAB1-8EEC-47A8-B420-AD7CB333056A)]
 interface nsIAnnotationService : nsISupports
 {
     /**
      * Valid values for aExpiration, which sets the expiration policy for your
      * annotation. The times for the days, weeks and months policies are
      * measured since the last visit date of the page in question. These
      * will not expire so long as the user keeps visiting the page from time
      * to time.
      */
     // For temporary data that can be discarded when the user exits.
     // Removed at application exit.
     const unsigned short EXPIRE_SESSION = 0;
     // NOTE: 1 is skipped due to its temporary use as EXPIRE_NEVER in bug #319455.
     // For general page settings, things the user is interested in seeing
     // if they come back to this page some time in the near future.
     // Removed at 30 days.
     const unsigned short EXPIRE_WEEKS = 2;
     // Something that the user will be interested in seeing in their
     // history like favicons. If they haven't visited a page in a couple
     // of months, they probably aren't interested in many other annotations,
     // the positions of things, or other stuff you create, so put that in
     // the weeks policy.
     // Removed at 180 days.
     const unsigned short EXPIRE_MONTHS = 3;
     // For annotations that only live as long as the URI is in the database.
     // A page annotation will expire if the page has no visits
     // and is not bookmarked.
     // An item annotation will expire when the item is deleted.
     const unsigned short EXPIRE_NEVER = 4;
     // For annotations that only live as long as the URI has visits.
     // Valid only for page annotations.
     const unsigned short EXPIRE_WITH_HISTORY = 5;
     // For short-lived temporary data that you still want to outlast a session.
     // Removed at 7 days.
     const unsigned short EXPIRE_DAYS = 6;
     // type constants
     const unsigned short TYPE_INT32  = 1;
     const unsigned short TYPE_DOUBLE = 2;
     const unsigned short TYPE_STRING = 3;
     const unsigned short TYPE_INT64  = 5;
     /**
      * Sets an annotation, overwriting any previous annotation with the same
      * URL/name. IT IS YOUR JOB TO NAMESPACE YOUR ANNOTATION NAMES.
      * Use the form "namespace/value", so your name would be like
      * "bills_extension/page_state" or "history/thumbnail".
      *
      * Do not use characters that are not valid in URLs such as spaces, ":",
      * commas, or most other symbols. You should stick to ASCII letters and
      * numbers plus "_", "-", and "/".
      *
      * aExpiration is one of EXPIRE_* above. aFlags should be 0 for now, some
      * flags will be defined in the future.
      *
      * NOTE: ALL PAGE ANNOTATIONS WILL GET DELETED WHEN THE PAGE IS REMOVED FROM
      * HISTORY IF THE PAGE IS NOT BOOKMARKED. This means that if you create an
      * annotation on an unvisited URI, it will get deleted when the browser
      * shuts down. Otherwise, URIs can exist in history as annotations but the
      * user has no way of knowing it, potentially violating their privacy
      * expectations about actions such as "Clear history".
      * If there is an important annotation that the user or extension wants to
      * keep, you should add a bookmark for the page and use an EXPIRE_NEVER
      * annotation.  This will ensure the annotation exists until the item is
      * removed by the user.
      * See EXPIRE_* constants above for further information.
      *
      * The annotation "favicon" is special. Favicons are stored in the favicon
      * service, but are special cased in the protocol handler so they look like
      * annotations. Do not set favicons using this service, it will not work.
      *
      * Only C++ consumers may use the type-specific methods.
      *
      * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
      */
     void setPageAnnotation(in nsIURI aURI,
                            in AUTF8String aName,
                            in nsIVariant aValue,
                            in long aFlags,
                            in unsigned short aExpiration);
     void setItemAnnotation(in long long aItemId,
                            in AUTF8String aName,
                            in nsIVariant aValue,
                            in long aFlags,
                            in unsigned short aExpiration);
     /**
      * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
      */
     [noscript] void setPageAnnotationString(in nsIURI aURI,
                                             in AUTF8String aName,
                                             in AString aValue,
                                             in long aFlags,
                                             in unsigned short aExpiration);
     [noscript] void setItemAnnotationString(in long long aItemId,
                                             in AUTF8String aName,
                                             in AString aValue,
                                             in long aFlags,
                                             in unsigned short aExpiration);
     /**
      * Sets an annotation just like setAnnotationString, but takes an Int32 as
      * input.
      *
      * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
      */
     [noscript] void setPageAnnotationInt32(in nsIURI aURI,
                                            in AUTF8String aName,
                                            in long aValue,
                                            in long aFlags,
                                            in unsigned short aExpiration);
     [noscript] void setItemAnnotationInt32(in long long aItemId,
                                            in AUTF8String aName,
                                            in long aValue,
                                            in long aFlags,
                                            in unsigned short aExpiration);
     /**
      * Sets an annotation just like setAnnotationString, but takes an Int64 as
      * input.
      *
      * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
      */
     [noscript] void setPageAnnotationInt64(in nsIURI aURI,
                                            in AUTF8String aName,
                                            in long long aValue,
                                            in long aFlags,
                                            in unsigned short aExpiration);
     [noscript] void setItemAnnotationInt64(in long long aItemId,
                                            in AUTF8String aName,
                                            in long long aValue,
                                            in long aFlags,
                                            in unsigned short aExpiration);
     /**
      * Sets an annotation just like setAnnotationString, but takes a double as
      * input.
      *
      * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
      */
     [noscript] void setPageAnnotationDouble(in nsIURI aURI,
                                             in AUTF8String aName,
                                             in double aValue,
                                             in long aFlags,
                                             in unsigned short aExpiration);
     [noscript] void setItemAnnotationDouble(in long long aItemId,
                                             in AUTF8String aName,
                                             in double aValue,
                                             in long aFlags,
                                             in unsigned short aExpiration);
     /**
      * Retrieves the value of a given annotation. Throws an error if the
      * annotation does not exist. C++ consumers may use the type-specific
      * methods.
      *
      * The type-specific methods throw if the given annotation is set in
      * a different type.
      */
     nsIVariant getPageAnnotation(in nsIURI aURI,
                                  in AUTF8String aName);
     nsIVariant getItemAnnotation(in long long aItemId,
                                  in AUTF8String aName);
     /**
      * @see getPageAnnotation
      */
     [noscript] AString getPageAnnotationString(in nsIURI aURI,
                                                in AUTF8String aName);
     [noscript] AString getItemAnnotationString(in long long aItemId,
                                                in AUTF8String aName);
     /**
      * @see getPageAnnotation
      */
     [noscript] long getPageAnnotationInt32(in nsIURI aURI,
                                            in AUTF8String aName);
     [noscript] long getItemAnnotationInt32(in long long aItemId,
                                            in AUTF8String aName);
     /**
      * @see getPageAnnotation
      */
     [noscript] long long getPageAnnotationInt64(in nsIURI aURI,
                                                 in AUTF8String aName);
     [noscript] long long getItemAnnotationInt64(in long long aItemId,
                                                 in AUTF8String aName);
     /**
      * @see getPageAnnotation
      */
     [noscript] double getPageAnnotationDouble(in nsIURI aURI,
                                               in AUTF8String aName);
     [noscript] double getItemAnnotationDouble(in long long aItemId,
                                               in AUTF8String aName);
     /**
      * Retrieves info about an existing annotation.
      *
      * aType will be one of TYPE_* constansts above
      *
      * example JS:
      *   var flags = {}, exp = {}, type = {};
      *   annotator.getAnnotationInfo(myURI, "foo", flags, exp, type);
      *   // now you can use 'exp.value' and 'flags.value'
      */
     void getPageAnnotationInfo(in nsIURI aURI,
                                in AUTF8String aName,
                                out int32_t aFlags,
                                out unsigned short aExpiration,
                                out unsigned short aType);
     void getItemAnnotationInfo(in long long aItemId,
                                in AUTF8String aName,
                                out long aFlags,
                                out unsigned short aExpiration,
                                out unsigned short aType);
     /**
      * Retrieves the type of an existing annotation
      * Use getAnnotationInfo if you need this along with the mime-type etc.
      *
      * @param aURI
      *        the uri on which the annotation is set
      * @param aName
      *        the annotation name
      * @return one of the TYPE_* constants above
      * @throws if the annotation is not set
      */
     uint16_t getPageAnnotationType(in nsIURI aURI,
                                    in AUTF8String aName);
     uint16_t getItemAnnotationType(in long long aItemId,
                                    in AUTF8String aName);
     /**
      * Returns a list of all URIs having a given annotation.
      */
     void getPagesWithAnnotation(
       in AUTF8String name,
       [optional] out unsigned long resultCount,
       [retval, array, size_is(resultCount)] out nsIURI results);
     void getItemsWithAnnotation(
       in AUTF8String name,
       [optional] out unsigned long resultCount,
       [retval, array, size_is(resultCount)] out long long results);
     /**
      * Returns a list of mozIAnnotation(s), having a given annotation name.
      *
      * @param name
      *        The annotation to search for.
      * @return list of mozIAnnotation objects.
      */
     void getAnnotationsWithName(
         in AUTF8String name,
         [optional] out unsigned long count,
         [retval, array, size_is(count)] out mozIAnnotatedResult results);
     /**
      * Get the names of all annotations for this URI.
      *
      * example JS:
      *   var annotations = annotator.getPageAnnotations(myURI, {});
      */
     void getPageAnnotationNames(
       in nsIURI aURI,
       [optional] out unsigned long count,
       [retval, array, size_is(count)] out nsIVariant result);
     void getItemAnnotationNames(
       in long long aItemId,
       [optional] out unsigned long count,
       [retval, array, size_is(count)] out nsIVariant result);
     /**
      * Test for annotation existence.
      */
     boolean pageHasAnnotation(in nsIURI aURI,
                               in AUTF8String aName);
     boolean itemHasAnnotation(in long long aItemId,
                               in AUTF8String aName);
     /**
      * Removes a specific annotation. Succeeds even if the annotation is
      * not found.
      */
     void removePageAnnotation(in nsIURI aURI,
                               in AUTF8String aName);
     void removeItemAnnotation(in long long aItemId,
                               in AUTF8String aName);
     /**
      * Removes all annotations for the given page/item.
      * We may want some other similar functions to get annotations with given
      * flags (once we have flags defined).
      */
     void removePageAnnotations(in nsIURI aURI);
     void removeItemAnnotations(in long long aItemId);
     /**
      * Copies all annotations from the source to the destination URI/item. If
      * the destination already has an annotation with the same name as one on
      * the source, it will be overwritten if aOverwriteDest is set. Otherwise,
      * the original annotation will be preferred.
      *
      * All the source annotations will stay as-is. If you don't want them
      * any more, use removePageAnnotations on that URI.
      */
     void copyPageAnnotations(in nsIURI aSourceURI,
                              in nsIURI aDestURI,
                              in boolean aOverwriteDest);
     void copyItemAnnotations(in long long aSourceItemId,
                              in long long aDestItemId,
                              in boolean aOverwriteDest);
     /**
      * Adds an annotation observer. The annotation service will keep an owning
      * reference to the observer object.
      */
     void addObserver(in nsIAnnotationObserver aObserver);
     /**
      * Removes an annotaton observer previously registered by addObserver.
      */
     void removeObserver(in nsIAnnotationObserver aObserver);
 };
 /**
  * Represents a place annotated with a given annotation.  If a place has
  * multiple annotations, it can be represented by multiple
  * mozIAnnotatedResult(s).
  */
 [scriptable, uuid(81fd0188-db6a-492e-80b6-f6414913b396)]
 interface mozIAnnotatedResult : nsISupports
 {
     /**
      * The globally unique identifier of the place with this annotation.
      *
      * @note if itemId is valid this is the guid of the bookmark, otherwise
      *       of the page.
      */
     readonly attribute AUTF8String guid;
     /**
      * The URI of the place with this annotation, if available, null otherwise.
      */
     readonly attribute nsIURI uri;
     /**
      * The bookmark id of the place with this annotation, if available,
      * -1 otherwise.
      *
      * @note if itemId is -1, it doesn't mean the page is not bookmarked, just
      *       that this annotation is relative to the page, not to the bookmark.
      */
     readonly attribute long long itemId;
     /**
      * Name of the annotation.
      */
     readonly attribute AUTF8String annotationName;
     /**
      * Value of the annotation.
      */
     readonly attribute nsIVariant annotationValue;
 };

The Tor Browser / annotate

toolkit/components/places/nsIAnnotationService.idl@b8a032363ba2 (annotated)

toolkit/components/places/nsIAnnotationService.idl