diff options
Diffstat (limited to 'toolkit/components/places/nsIAnnotationService.idl')
| -rw-r--r-- | toolkit/components/places/nsIAnnotationService.idl | 422 |
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; +}; |