зеркало из https://github.com/mozilla/gecko-dev.git
409 строки
16 KiB
Plaintext
409 строки
16 KiB
Plaintext
/* -*- 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;
|
|
};
|