summaryrefslogtreecommitdiffstats
path: root/toolkit/components/places/nsIAnnotationService.idl
diff options
context:
space:
mode:
Diffstat (limited to 'toolkit/components/places/nsIAnnotationService.idl')
-rw-r--r--toolkit/components/places/nsIAnnotationService.idl422
1 files changed, 422 insertions, 0 deletions
diff --git a/toolkit/components/places/nsIAnnotationService.idl b/toolkit/components/places/nsIAnnotationService.idl
new file mode 100644
index 000000000..bdd417ece
--- /dev/null
+++ b/toolkit/components/places/nsIAnnotationService.idl
@@ -0,0 +1,422 @@
+/* -*- 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,
+ in unsigned short aSource);
+
+ /**
+ * 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,
+ in unsigned short aSource);
+};
+
+[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.
+ *
+ * For item annotations, aSource should be a change source constant from
+ * nsINavBookmarksService::SOURCE_*, and defaults to SOURCE_DEFAULT if
+ * omitted.
+ *
+ * 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,
+ [optional] in unsigned short aSource);
+
+ /**
+ * @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,
+ [optional] in unsigned short aSource);
+
+ /**
+ * 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,
+ [optional] in unsigned short aSource);
+
+ /**
+ * 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,
+ [optional] in unsigned short aSource);
+
+ /**
+ * 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,
+ [optional] in unsigned short aSource);
+
+ /**
+ * 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,
+ [optional] in unsigned short aSource);
+
+ /**
+ * 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,
+ [optional] in unsigned short aSource);
+
+ /**
+ * 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,
+ [optional] in unsigned short aSource);
+
+ /**
+ * 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;
+};