mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-26 06:11:37 +00:00
0d4d59a191
Depends on D4062 Differential Revision: https://phabricator.services.mozilla.com/D4063 --HG-- extra : moz-landing-system : lando
133 lines
4.7 KiB
Plaintext
133 lines
4.7 KiB
Plaintext
/* -*- 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 ===
|
|
*
|
|
* See https://bugzilla.mozilla.org/show_bug.cgi?id=699844
|
|
*
|
|
*
|
|
*/
|
|
|
|
[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);
|
|
|
|
/**
|
|
* 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 getItemAnnotationInfo(in long long aItemId,
|
|
in AUTF8String aName,
|
|
out nsIVariant aValue,
|
|
out long aFlags,
|
|
out unsigned short aExpiration,
|
|
out unsigned short aType);
|
|
|
|
/**
|
|
* Get the names of all annotations for this URI.
|
|
*
|
|
* example JS:
|
|
* var annotations = annotator.getPageAnnotations(myURI, {});
|
|
*/
|
|
void getItemAnnotationNames(
|
|
in long long aItemId,
|
|
[optional] out unsigned long count,
|
|
[retval, array, size_is(count)] out nsIVariant result);
|
|
|
|
/**
|
|
* 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);
|
|
};
|