nsIAnnotationService.idl
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is Annotation code
*
* The Initial Developer of the Original Code is
* Google Inc.
* Portions created by the Initial Developer are Copyright (C) 2005
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
* Brett Wilson <brettw@gmail.com>
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#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);
};
