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