/* -*- 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.
*/voidonPageAnnotationSet(in nsIURI aPage,
in AUTF8String aName);
voidonItemAnnotationSet(in longlong aItemId,
in AUTF8String aName,
in unsignedshort 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).
*/voidonPageAnnotationRemoved(in nsIURI aURI,
in AUTF8String aName);
voidonItemAnnotationRemoved(in longlong aItemId,
in AUTF8String aName,
in unsignedshort 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.constunsignedshortEXPIRE_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. constunsignedshortEXPIRE_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.constunsignedshortEXPIRE_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.constunsignedshortEXPIRE_NEVER = 4;
// For annotations that only live as long as the URI has visits.// Valid only for page annotations.constunsignedshortEXPIRE_WITH_HISTORY = 5;
// For short-lived temporary data that you still want to outlast a session.// Removed at 7 days.constunsignedshortEXPIRE_DAYS = 6;
// type constantsconstunsignedshortTYPE_INT32 = 1;
constunsignedshortTYPE_DOUBLE = 2;
constunsignedshortTYPE_STRING = 3;
constunsignedshortTYPE_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.
*/voidsetPageAnnotation(in nsIURI aURI,
in AUTF8String aName,
in nsIVariant aValue,
in long aFlags,
in unsignedshort aExpiration);
voidsetItemAnnotation(in longlong aItemId,
in AUTF8String aName,
in nsIVariant aValue,
in long aFlags,
in unsignedshort aExpiration,
[optional] in unsignedshort aSource);
/**
* @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
*/ [noscript] voidsetPageAnnotationString(in nsIURI aURI,
in AUTF8String aName,
in AString aValue,
in long aFlags,
in unsignedshort aExpiration);
[noscript] voidsetItemAnnotationString(in longlong aItemId,
in AUTF8String aName,
in AString aValue,
in long aFlags,
in unsignedshort aExpiration,
[optional] in unsignedshort 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] voidsetPageAnnotationInt32(in nsIURI aURI,
in AUTF8String aName,
in long aValue,
in long aFlags,
in unsignedshort aExpiration);
[noscript] voidsetItemAnnotationInt32(in longlong aItemId,
in AUTF8String aName,
in long aValue,
in long aFlags,
in unsignedshort aExpiration,
[optional] in unsignedshort 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] voidsetPageAnnotationInt64(in nsIURI aURI,
in AUTF8String aName,
in longlong aValue,
in long aFlags,
in unsignedshort aExpiration);
[noscript] voidsetItemAnnotationInt64(in longlong aItemId,
in AUTF8String aName,
in longlong aValue,
in long aFlags,
in unsignedshort aExpiration,
[optional] in unsignedshort 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] voidsetPageAnnotationDouble(in nsIURI aURI,
in AUTF8String aName,
in double aValue,
in long aFlags,
in unsignedshort aExpiration);
[noscript] voidsetItemAnnotationDouble(in longlong aItemId,
in AUTF8String aName,
in double aValue,
in long aFlags,
in unsignedshort aExpiration,
[optional] in unsignedshort 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 longlong aItemId,
in AUTF8String aName);
/**
* @see getPageAnnotation
*/ [noscript] AString getPageAnnotationString(in nsIURI aURI,
in AUTF8String aName);
[noscript] AString getItemAnnotationString(in longlong aItemId,
in AUTF8String aName);
/**
* @see getPageAnnotation
*/ [noscript] longgetPageAnnotationInt32(in nsIURI aURI,
in AUTF8String aName);
[noscript] longgetItemAnnotationInt32(in longlong aItemId,
in AUTF8String aName);
/**
* @see getPageAnnotation
*/ [noscript] longlonggetPageAnnotationInt64(in nsIURI aURI,
in AUTF8String aName);
[noscript] longlonggetItemAnnotationInt64(in longlong aItemId,
in AUTF8String aName);
/**
* @see getPageAnnotation
*/ [noscript] doublegetPageAnnotationDouble(in nsIURI aURI,
in AUTF8String aName);
[noscript] doublegetItemAnnotationDouble(in longlong 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'
*/voidgetPageAnnotationInfo(in nsIURI aURI,
in AUTF8String aName,
out int32_t aFlags,
out unsignedshort aExpiration,
out unsignedshort aType);
voidgetItemAnnotationInfo(in longlong aItemId,
in AUTF8String aName,
out long aFlags,
out unsignedshort aExpiration,
out unsignedshort 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_tgetPageAnnotationType(in nsIURI aURI,
in AUTF8String aName);
uint16_tgetItemAnnotationType(in longlong aItemId,
in AUTF8String aName);
/**
* Returns a list of all URIs having a given annotation.
*/voidgetPagesWithAnnotation(
in AUTF8String name,
[optional] out unsignedlong resultCount,
[retval, array, size_is(resultCount)] out nsIURI results);
voidgetItemsWithAnnotation(
in AUTF8String name,
[optional] out unsignedlong resultCount,
[retval, array, size_is(resultCount)] out longlong results);
/**
* Returns a list of mozIAnnotation(s), having a given annotation name.
*
* @param name
* The annotation to search for.
* @return list of mozIAnnotation objects.
*/voidgetAnnotationsWithName(
in AUTF8String name,
[optional] out unsignedlong 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, {});
*/voidgetPageAnnotationNames(
in nsIURI aURI,
[optional] out unsignedlong count,
[retval, array, size_is(count)] out nsIVariant result);
voidgetItemAnnotationNames(
in longlong aItemId,
[optional] out unsignedlong count,
[retval, array, size_is(count)] out nsIVariant result);
/**
* Test for annotation existence.
*/ boolean pageHasAnnotation(in nsIURI aURI,
in AUTF8String aName);
boolean itemHasAnnotation(in longlong aItemId,
in AUTF8String aName);
/**
* Removes a specific annotation. Succeeds even if the annotation is
* not found.
*/voidremovePageAnnotation(in nsIURI aURI,
in AUTF8String aName);
voidremoveItemAnnotation(in longlong aItemId,
in AUTF8String aName,
[optional] in unsignedshort 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).
*/voidremovePageAnnotations(in nsIURI aURI);
voidremoveItemAnnotations(in longlong aItemId,
[optional] in unsignedshort 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.
*/voidcopyPageAnnotations(in nsIURI aSourceURI,
in nsIURI aDestURI,
in boolean aOverwriteDest);
voidcopyItemAnnotations(in longlong aSourceItemId,
in longlong aDestItemId,
in boolean aOverwriteDest,
[optional] in unsignedshort aSource);
/**
* Adds an annotation observer. The annotation service will keep an owning
* reference to the observer object.
*/voidaddObserver(in nsIAnnotationObserver aObserver);
/**
* Removes an annotaton observer previously registered by addObserver.
*/voidremoveObserver(in nsIAnnotationObserver aObserver);
/**
* Gets an array of registered nsIAnnotationObserver objects.
*/voidgetObservers([optional] out unsignedlong count,
[retval, array, size_is(count)] out nsIAnnotationObserver observers);
};
/**
* 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 longlongitemId;
/**
* Name of the annotation.
*/ readonly attribute AUTF8String annotationName;
/**
* Value of the annotation.
*/ readonly attribute nsIVariant annotationValue;
};