The Tor Browser / file comparison

comparison: toolkit/components/places/nsIAnnotationService.idl

toolkit/components/places/nsIAnnotationService.idl

changeset 0
6474c204b198
equal deleted inserted replaced
-1:000000000000 0:2d8a5e43ef66
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 interface mozIAnnotatedResult;
11
12 [scriptable, uuid(63fe98e0-6889-4c2c-ac9f-703e4bc25027)]
13 interface nsIAnnotationObserver : nsISupports
14 {
15 /**
16 * Called when an annotation value is set. It could be a new annotation,
17 * or it could be a new value for an existing annotation.
18 */
19 void onPageAnnotationSet(in nsIURI aPage,
20 in AUTF8String aName);
21 void onItemAnnotationSet(in long long aItemId,
22 in AUTF8String aName);
23
24 /**
25 * Called when an annotation is deleted. If aName is empty, then ALL
26 * annotations for the given URI have been deleted. This is not called when
27 * annotations are expired (normally happens when the app exits).
28 */
29 void onPageAnnotationRemoved(in nsIURI aURI,
30 in AUTF8String aName);
31 void onItemAnnotationRemoved(in long long aItemId,
32 in AUTF8String aName);
33 };
34
35 [scriptable, uuid(D4CDAAB1-8EEC-47A8-B420-AD7CB333056A)]
36 interface nsIAnnotationService : nsISupports
37 {
38 /**
39 * Valid values for aExpiration, which sets the expiration policy for your
40 * annotation. The times for the days, weeks and months policies are
41 * measured since the last visit date of the page in question. These
42 * will not expire so long as the user keeps visiting the page from time
43 * to time.
44 */
45
46 // For temporary data that can be discarded when the user exits.
47 // Removed at application exit.
48 const unsigned short EXPIRE_SESSION = 0;
49
50 // NOTE: 1 is skipped due to its temporary use as EXPIRE_NEVER in bug #319455.
51
52 // For general page settings, things the user is interested in seeing
53 // if they come back to this page some time in the near future.
54 // Removed at 30 days.
55 const unsigned short EXPIRE_WEEKS = 2;
56
57 // Something that the user will be interested in seeing in their
58 // history like favicons. If they haven't visited a page in a couple
59 // of months, they probably aren't interested in many other annotations,
60 // the positions of things, or other stuff you create, so put that in
61 // the weeks policy.
62 // Removed at 180 days.
63 const unsigned short EXPIRE_MONTHS = 3;
64
65 // For annotations that only live as long as the URI is in the database.
66 // A page annotation will expire if the page has no visits
67 // and is not bookmarked.
68 // An item annotation will expire when the item is deleted.
69 const unsigned short EXPIRE_NEVER = 4;
70
71 // For annotations that only live as long as the URI has visits.
72 // Valid only for page annotations.
73 const unsigned short EXPIRE_WITH_HISTORY = 5;
74
75 // For short-lived temporary data that you still want to outlast a session.
76 // Removed at 7 days.
77 const unsigned short EXPIRE_DAYS = 6;
78
79 // type constants
80 const unsigned short TYPE_INT32 = 1;
81 const unsigned short TYPE_DOUBLE = 2;
82 const unsigned short TYPE_STRING = 3;
83 const unsigned short TYPE_INT64 = 5;
84
85 /**
86 * Sets an annotation, overwriting any previous annotation with the same
87 * URL/name. IT IS YOUR JOB TO NAMESPACE YOUR ANNOTATION NAMES.
88 * Use the form "namespace/value", so your name would be like
89 * "bills_extension/page_state" or "history/thumbnail".
90 *
91 * Do not use characters that are not valid in URLs such as spaces, ":",
92 * commas, or most other symbols. You should stick to ASCII letters and
93 * numbers plus "_", "-", and "/".
94 *
95 * aExpiration is one of EXPIRE_* above. aFlags should be 0 for now, some
96 * flags will be defined in the future.
97 *
98 * NOTE: ALL PAGE ANNOTATIONS WILL GET DELETED WHEN THE PAGE IS REMOVED FROM
99 * HISTORY IF THE PAGE IS NOT BOOKMARKED. This means that if you create an
100 * annotation on an unvisited URI, it will get deleted when the browser
101 * shuts down. Otherwise, URIs can exist in history as annotations but the
102 * user has no way of knowing it, potentially violating their privacy
103 * expectations about actions such as "Clear history".
104 * If there is an important annotation that the user or extension wants to
105 * keep, you should add a bookmark for the page and use an EXPIRE_NEVER
106 * annotation. This will ensure the annotation exists until the item is
107 * removed by the user.
108 * See EXPIRE_* constants above for further information.
109 *
110 * The annotation "favicon" is special. Favicons are stored in the favicon
111 * service, but are special cased in the protocol handler so they look like
112 * annotations. Do not set favicons using this service, it will not work.
113 *
114 * Only C++ consumers may use the type-specific methods.
115 *
116 * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
117 */
118 void setPageAnnotation(in nsIURI aURI,
119 in AUTF8String aName,
120 in nsIVariant aValue,
121 in long aFlags,
122 in unsigned short aExpiration);
123 void setItemAnnotation(in long long aItemId,
124 in AUTF8String aName,
125 in nsIVariant aValue,
126 in long aFlags,
127 in unsigned short aExpiration);
128
129 /**
130 * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
131 */
132 [noscript] void setPageAnnotationString(in nsIURI aURI,
133 in AUTF8String aName,
134 in AString aValue,
135 in long aFlags,
136 in unsigned short aExpiration);
137 [noscript] void setItemAnnotationString(in long long aItemId,
138 in AUTF8String aName,
139 in AString aValue,
140 in long aFlags,
141 in unsigned short aExpiration);
142
143 /**
144 * Sets an annotation just like setAnnotationString, but takes an Int32 as
145 * input.
146 *
147 * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
148 */
149 [noscript] void setPageAnnotationInt32(in nsIURI aURI,
150 in AUTF8String aName,
151 in long aValue,
152 in long aFlags,
153 in unsigned short aExpiration);
154 [noscript] void setItemAnnotationInt32(in long long aItemId,
155 in AUTF8String aName,
156 in long aValue,
157 in long aFlags,
158 in unsigned short aExpiration);
159
160 /**
161 * Sets an annotation just like setAnnotationString, but takes an Int64 as
162 * input.
163 *
164 * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
165 */
166 [noscript] void setPageAnnotationInt64(in nsIURI aURI,
167 in AUTF8String aName,
168 in long long aValue,
169 in long aFlags,
170 in unsigned short aExpiration);
171 [noscript] void setItemAnnotationInt64(in long long aItemId,
172 in AUTF8String aName,
173 in long long aValue,
174 in long aFlags,
175 in unsigned short aExpiration);
176
177 /**
178 * Sets an annotation just like setAnnotationString, but takes a double as
179 * input.
180 *
181 * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
182 */
183 [noscript] void setPageAnnotationDouble(in nsIURI aURI,
184 in AUTF8String aName,
185 in double aValue,
186 in long aFlags,
187 in unsigned short aExpiration);
188 [noscript] void setItemAnnotationDouble(in long long aItemId,
189 in AUTF8String aName,
190 in double aValue,
191 in long aFlags,
192 in unsigned short aExpiration);
193
194 /**
195 * Retrieves the value of a given annotation. Throws an error if the
196 * annotation does not exist. C++ consumers may use the type-specific
197 * methods.
198 *
199 * The type-specific methods throw if the given annotation is set in
200 * a different type.
201 */
202 nsIVariant getPageAnnotation(in nsIURI aURI,
203 in AUTF8String aName);
204 nsIVariant getItemAnnotation(in long long aItemId,
205 in AUTF8String aName);
206
207 /**
208 * @see getPageAnnotation
209 */
210 [noscript] AString getPageAnnotationString(in nsIURI aURI,
211 in AUTF8String aName);
212 [noscript] AString getItemAnnotationString(in long long aItemId,
213 in AUTF8String aName);
214
215 /**
216 * @see getPageAnnotation
217 */
218 [noscript] long getPageAnnotationInt32(in nsIURI aURI,
219 in AUTF8String aName);
220 [noscript] long getItemAnnotationInt32(in long long aItemId,
221 in AUTF8String aName);
222
223 /**
224 * @see getPageAnnotation
225 */
226 [noscript] long long getPageAnnotationInt64(in nsIURI aURI,
227 in AUTF8String aName);
228 [noscript] long long getItemAnnotationInt64(in long long aItemId,
229 in AUTF8String aName);
230
231 /**
232 * @see getPageAnnotation
233 */
234 [noscript] double getPageAnnotationDouble(in nsIURI aURI,
235 in AUTF8String aName);
236 [noscript] double getItemAnnotationDouble(in long long aItemId,
237 in AUTF8String aName);
238
239 /**
240 * Retrieves info about an existing annotation.
241 *
242 * aType will be one of TYPE_* constansts above
243 *
244 * example JS:
245 * var flags = {}, exp = {}, type = {};
246 * annotator.getAnnotationInfo(myURI, "foo", flags, exp, type);
247 * // now you can use 'exp.value' and 'flags.value'
248 */
249 void getPageAnnotationInfo(in nsIURI aURI,
250 in AUTF8String aName,
251 out int32_t aFlags,
252 out unsigned short aExpiration,
253 out unsigned short aType);
254 void getItemAnnotationInfo(in long long aItemId,
255 in AUTF8String aName,
256 out long aFlags,
257 out unsigned short aExpiration,
258 out unsigned short aType);
259
260 /**
261 * Retrieves the type of an existing annotation
262 * Use getAnnotationInfo if you need this along with the mime-type etc.
263 *
264 * @param aURI
265 * the uri on which the annotation is set
266 * @param aName
267 * the annotation name
268 * @return one of the TYPE_* constants above
269 * @throws if the annotation is not set
270 */
271 uint16_t getPageAnnotationType(in nsIURI aURI,
272 in AUTF8String aName);
273 uint16_t getItemAnnotationType(in long long aItemId,
274 in AUTF8String aName);
275
276 /**
277 * Returns a list of all URIs having a given annotation.
278 */
279 void getPagesWithAnnotation(
280 in AUTF8String name,
281 [optional] out unsigned long resultCount,
282 [retval, array, size_is(resultCount)] out nsIURI results);
283 void getItemsWithAnnotation(
284 in AUTF8String name,
285 [optional] out unsigned long resultCount,
286 [retval, array, size_is(resultCount)] out long long results);
287
288 /**
289 * Returns a list of mozIAnnotation(s), having a given annotation name.
290 *
291 * @param name
292 * The annotation to search for.
293 * @return list of mozIAnnotation objects.
294 */
295 void getAnnotationsWithName(
296 in AUTF8String name,
297 [optional] out unsigned long count,
298 [retval, array, size_is(count)] out mozIAnnotatedResult results);
299
300 /**
301 * Get the names of all annotations for this URI.
302 *
303 * example JS:
304 * var annotations = annotator.getPageAnnotations(myURI, {});
305 */
306 void getPageAnnotationNames(
307 in nsIURI aURI,
308 [optional] out unsigned long count,
309 [retval, array, size_is(count)] out nsIVariant result);
310 void getItemAnnotationNames(
311 in long long aItemId,
312 [optional] out unsigned long count,
313 [retval, array, size_is(count)] out nsIVariant result);
314
315 /**
316 * Test for annotation existence.
317 */
318 boolean pageHasAnnotation(in nsIURI aURI,
319 in AUTF8String aName);
320 boolean itemHasAnnotation(in long long aItemId,
321 in AUTF8String aName);
322
323 /**
324 * Removes a specific annotation. Succeeds even if the annotation is
325 * not found.
326 */
327 void removePageAnnotation(in nsIURI aURI,
328 in AUTF8String aName);
329 void removeItemAnnotation(in long long aItemId,
330 in AUTF8String aName);
331
332 /**
333 * Removes all annotations for the given page/item.
334 * We may want some other similar functions to get annotations with given
335 * flags (once we have flags defined).
336 */
337 void removePageAnnotations(in nsIURI aURI);
338 void removeItemAnnotations(in long long aItemId);
339
340 /**
341 * Copies all annotations from the source to the destination URI/item. If
342 * the destination already has an annotation with the same name as one on
343 * the source, it will be overwritten if aOverwriteDest is set. Otherwise,
344 * the original annotation will be preferred.
345 *
346 * All the source annotations will stay as-is. If you don't want them
347 * any more, use removePageAnnotations on that URI.
348 */
349 void copyPageAnnotations(in nsIURI aSourceURI,
350 in nsIURI aDestURI,
351 in boolean aOverwriteDest);
352 void copyItemAnnotations(in long long aSourceItemId,
353 in long long aDestItemId,
354 in boolean aOverwriteDest);
355
356 /**
357 * Adds an annotation observer. The annotation service will keep an owning
358 * reference to the observer object.
359 */
360 void addObserver(in nsIAnnotationObserver aObserver);
361
362
363 /**
364 * Removes an annotaton observer previously registered by addObserver.
365 */
366 void removeObserver(in nsIAnnotationObserver aObserver);
367 };
368
369 /**
370 * Represents a place annotated with a given annotation. If a place has
371 * multiple annotations, it can be represented by multiple
372 * mozIAnnotatedResult(s).
373 */
374 [scriptable, uuid(81fd0188-db6a-492e-80b6-f6414913b396)]
375 interface mozIAnnotatedResult : nsISupports
376 {
377 /**
378 * The globally unique identifier of the place with this annotation.
379 *
380 * @note if itemId is valid this is the guid of the bookmark, otherwise
381 * of the page.
382 */
383 readonly attribute AUTF8String guid;
384
385 /**
386 * The URI of the place with this annotation, if available, null otherwise.
387 */
388 readonly attribute nsIURI uri;
389
390 /**
391 * The bookmark id of the place with this annotation, if available,
392 * -1 otherwise.
393 *
394 * @note if itemId is -1, it doesn't mean the page is not bookmarked, just
395 * that this annotation is relative to the page, not to the bookmark.
396 */
397 readonly attribute long long itemId;
398
399 /**
400 * Name of the annotation.
401 */
402 readonly attribute AUTF8String annotationName;
403
404 /**
405 * Value of the annotation.
406 */
407 readonly attribute nsIVariant annotationValue;
408 };

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial