/* -*- 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; [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(ba249b58-346f-42a9-a393-203ae34ec6c4)] 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_BINARY = 4; 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. * * Binary annotations should be set using * setItemAnnotationBinary/setPageAnnotationBinary. For other types, 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); /** * Sets an annotation just like setAnnotationString, but takes binary data * as input. You MUST supply a valid MIME type. * * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist. */ void setPageAnnotationBinary(in nsIURI aURI, in AUTF8String aName, [const,array,size_is(aDataLen)] in octet aData, in unsigned long aDataLen, in AUTF8String aMimeType, in long aFlags, in unsigned short aExpiration); void setItemAnnotationBinary(in long long aItemId, in AUTF8String aName, [const,array,size_is(aDataLen)] in octet aData, in unsigned long aDataLen, in AUTF8String aMimeType, in long aFlags, in unsigned short aExpiration); /** * Retrieves the value of a given annotation. Throws an error if the * annotation does not exist. Throws for binary annotations, for which * getPageAnnotationBinary/getItemAnnotationBinary should be used. 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); /** * @see getPageAnnotation. This also returns the * MIME type. */ void getPageAnnotationBinary(in nsIURI aURI, in AUTF8String aName, [array,size_is(aDataLen)] out octet aData, out unsigned long aDataLen, out AUTF8String aMimeType); void getItemAnnotationBinary(in long long aItemId, in AUTF8String aName, [array,size_is(aDataLen)] out octet aData, out unsigned long aDataLen, out AUTF8String aMimeType); /** * Retrieves info about an existing annotation. aMimeType will be empty * if the value was not binary data. * * aType will be one of TYPE_* constansts above * * example JS: * var flags = {}, exp = {}, mimeType = {}; * annotator.getAnnotationInfo(myURI, "foo", flags, exp, mimeType); * // now you can use 'exp.value' and 'flags.value' */ void getPageAnnotationInfo(in nsIURI aURI, in AUTF8String aName, out PRInt32 aFlags, out unsigned short aExpiration, out AUTF8String aMimeType, out unsigned short aType); void getItemAnnotationInfo(in long long aItemId, in AUTF8String aName, out long aFlags, out unsigned short aExpiration, out AUTF8String aMimeType, 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 */ PRUint16 getPageAnnotationType(in nsIURI aURI, in AUTF8String aName); PRUint16 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); /** * 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); /** * Returns a URI that can be used to access the given binary annotation. * This function does NOT check that the annotation exists. Also, note that * you can only load URIs for annotations that have have a valid MIME type * set by setAnnotationBinary. No non-URI valid chars in name, especially * colon, which will mess up parsing. */ nsIURI getAnnotationURI(in nsIURI aURI, in AUTF8String aName); };