Source code

Revision control

Other Tools

/* -*- 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;
/**
*
*
* THE ANNOTATION SERVICE API IS
*
* === D E P R E C A T E D ===
*
*
*
*/
[scriptable, uuid(D4CDAAB1-8EEC-47A8-B420-AD7CB333056A)]
interface nsIAnnotationService : nsISupports
{
/**
* Valid values for aExpiration, which sets the expiration policy for your
* annotation.
*/
// 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;
// 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.
*
* For item annotations, aSource should be a change source constant from
* nsINavBookmarksService::SOURCE_*, and defaults to SOURCE_DEFAULT if
* omitted. Setting an item annotation also notifies
* `nsINavBookmarkObserver::onItemChanged` for the affected item.
*
* 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 setItemAnnotation(in long long aItemId,
in AUTF8String aName,
in nsIVariant aValue,
in long aFlags,
in unsigned short aExpiration,
[optional] in unsigned short aSource,
[optional] in bool aDontUpdateLastModified);
/**
* 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 getItemAnnotation(in long long aItemId,
in AUTF8String aName);
/**
* Test for annotation existence.
*/
boolean itemHasAnnotation(in long long aItemId,
in AUTF8String aName);
/**
* Removes a specific annotation. Succeeds even if the annotation is
* not found.
*
* Removing an item annotation also notifies
* `nsINavBookmarkObserver::onItemChanged` for the affected item.
*/
void removeItemAnnotation(in long long aItemId,
in AUTF8String aName,
[optional] in unsigned short aSource);
};