Source code

Revision control

Other Tools

1
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2
/* This Source Code Form is subject to the terms of the Mozilla Public
3
* License, v. 2.0. If a copy of the MPL was not distributed with this
4
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6
#include "nsISupports.idl"
7
8
interface nsIURI;
9
interface nsIVariant;
10
11
/**
12
*
13
*
14
* THE ANNOTATION SERVICE API IS
15
*
16
* === D E P R E C A T E D ===
17
*
19
*
20
*
21
*/
22
23
[scriptable, uuid(D4CDAAB1-8EEC-47A8-B420-AD7CB333056A)]
24
interface nsIAnnotationService : nsISupports
25
{
26
/**
27
* Valid values for aExpiration, which sets the expiration policy for your
28
* annotation.
29
*/
30
31
// For annotations that only live as long as the URI is in the database.
32
// A page annotation will expire if the page has no visits
33
// and is not bookmarked.
34
// An item annotation will expire when the item is deleted.
35
const unsigned short EXPIRE_NEVER = 4;
36
37
// type constants
38
const unsigned short TYPE_INT32 = 1;
39
const unsigned short TYPE_DOUBLE = 2;
40
const unsigned short TYPE_STRING = 3;
41
const unsigned short TYPE_INT64 = 5;
42
43
/**
44
* Sets an annotation, overwriting any previous annotation with the same
45
* URL/name. IT IS YOUR JOB TO NAMESPACE YOUR ANNOTATION NAMES.
46
* Use the form "namespace/value", so your name would be like
47
* "bills_extension/page_state" or "history/thumbnail".
48
*
49
* Do not use characters that are not valid in URLs such as spaces, ":",
50
* commas, or most other symbols. You should stick to ASCII letters and
51
* numbers plus "_", "-", and "/".
52
*
53
* aExpiration is one of EXPIRE_* above. aFlags should be 0 for now, some
54
* flags will be defined in the future.
55
*
56
* For item annotations, aSource should be a change source constant from
57
* nsINavBookmarksService::SOURCE_*, and defaults to SOURCE_DEFAULT if
58
* omitted. Setting an item annotation also notifies
59
* `nsINavBookmarkObserver::onItemChanged` for the affected item.
60
*
61
* The annotation "favicon" is special. Favicons are stored in the favicon
62
* service, but are special cased in the protocol handler so they look like
63
* annotations. Do not set favicons using this service, it will not work.
64
*
65
* Only C++ consumers may use the type-specific methods.
66
*
67
* @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
68
*/
69
void setItemAnnotation(in long long aItemId,
70
in AUTF8String aName,
71
in nsIVariant aValue,
72
in long aFlags,
73
in unsigned short aExpiration,
74
[optional] in unsigned short aSource,
75
[optional] in bool aDontUpdateLastModified);
76
77
/**
78
* Retrieves the value of a given annotation. Throws an error if the
79
* annotation does not exist. C++ consumers may use the type-specific
80
* methods.
81
*
82
* The type-specific methods throw if the given annotation is set in
83
* a different type.
84
*/
85
nsIVariant getItemAnnotation(in long long aItemId,
86
in AUTF8String aName);
87
88
/**
89
* Test for annotation existence.
90
*/
91
boolean itemHasAnnotation(in long long aItemId,
92
in AUTF8String aName);
93
94
/**
95
* Removes a specific annotation. Succeeds even if the annotation is
96
* not found.
97
*
98
* Removing an item annotation also notifies
99
* `nsINavBookmarkObserver::onItemChanged` for the affected item.
100
*/
101
void removeItemAnnotation(in long long aItemId,
102
in AUTF8String aName,
103
[optional] in unsigned short aSource);
104
};