1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/components/places/nsIAnnotationService.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,408 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIURI;
1.12 +interface nsIVariant;
1.13 +interface mozIAnnotatedResult;
1.14 +
1.15 +[scriptable, uuid(63fe98e0-6889-4c2c-ac9f-703e4bc25027)]
1.16 +interface nsIAnnotationObserver : nsISupports
1.17 +{
1.18 + /**
1.19 + * Called when an annotation value is set. It could be a new annotation,
1.20 + * or it could be a new value for an existing annotation.
1.21 + */
1.22 + void onPageAnnotationSet(in nsIURI aPage,
1.23 + in AUTF8String aName);
1.24 + void onItemAnnotationSet(in long long aItemId,
1.25 + in AUTF8String aName);
1.26 +
1.27 + /**
1.28 + * Called when an annotation is deleted. If aName is empty, then ALL
1.29 + * annotations for the given URI have been deleted. This is not called when
1.30 + * annotations are expired (normally happens when the app exits).
1.31 + */
1.32 + void onPageAnnotationRemoved(in nsIURI aURI,
1.33 + in AUTF8String aName);
1.34 + void onItemAnnotationRemoved(in long long aItemId,
1.35 + in AUTF8String aName);
1.36 +};
1.37 +
1.38 +[scriptable, uuid(D4CDAAB1-8EEC-47A8-B420-AD7CB333056A)]
1.39 +interface nsIAnnotationService : nsISupports
1.40 +{
1.41 + /**
1.42 + * Valid values for aExpiration, which sets the expiration policy for your
1.43 + * annotation. The times for the days, weeks and months policies are
1.44 + * measured since the last visit date of the page in question. These
1.45 + * will not expire so long as the user keeps visiting the page from time
1.46 + * to time.
1.47 + */
1.48 +
1.49 + // For temporary data that can be discarded when the user exits.
1.50 + // Removed at application exit.
1.51 + const unsigned short EXPIRE_SESSION = 0;
1.52 +
1.53 + // NOTE: 1 is skipped due to its temporary use as EXPIRE_NEVER in bug #319455.
1.54 +
1.55 + // For general page settings, things the user is interested in seeing
1.56 + // if they come back to this page some time in the near future.
1.57 + // Removed at 30 days.
1.58 + const unsigned short EXPIRE_WEEKS = 2;
1.59 +
1.60 + // Something that the user will be interested in seeing in their
1.61 + // history like favicons. If they haven't visited a page in a couple
1.62 + // of months, they probably aren't interested in many other annotations,
1.63 + // the positions of things, or other stuff you create, so put that in
1.64 + // the weeks policy.
1.65 + // Removed at 180 days.
1.66 + const unsigned short EXPIRE_MONTHS = 3;
1.67 +
1.68 + // For annotations that only live as long as the URI is in the database.
1.69 + // A page annotation will expire if the page has no visits
1.70 + // and is not bookmarked.
1.71 + // An item annotation will expire when the item is deleted.
1.72 + const unsigned short EXPIRE_NEVER = 4;
1.73 +
1.74 + // For annotations that only live as long as the URI has visits.
1.75 + // Valid only for page annotations.
1.76 + const unsigned short EXPIRE_WITH_HISTORY = 5;
1.77 +
1.78 + // For short-lived temporary data that you still want to outlast a session.
1.79 + // Removed at 7 days.
1.80 + const unsigned short EXPIRE_DAYS = 6;
1.81 +
1.82 + // type constants
1.83 + const unsigned short TYPE_INT32 = 1;
1.84 + const unsigned short TYPE_DOUBLE = 2;
1.85 + const unsigned short TYPE_STRING = 3;
1.86 + const unsigned short TYPE_INT64 = 5;
1.87 +
1.88 + /**
1.89 + * Sets an annotation, overwriting any previous annotation with the same
1.90 + * URL/name. IT IS YOUR JOB TO NAMESPACE YOUR ANNOTATION NAMES.
1.91 + * Use the form "namespace/value", so your name would be like
1.92 + * "bills_extension/page_state" or "history/thumbnail".
1.93 + *
1.94 + * Do not use characters that are not valid in URLs such as spaces, ":",
1.95 + * commas, or most other symbols. You should stick to ASCII letters and
1.96 + * numbers plus "_", "-", and "/".
1.97 + *
1.98 + * aExpiration is one of EXPIRE_* above. aFlags should be 0 for now, some
1.99 + * flags will be defined in the future.
1.100 + *
1.101 + * NOTE: ALL PAGE ANNOTATIONS WILL GET DELETED WHEN THE PAGE IS REMOVED FROM
1.102 + * HISTORY IF THE PAGE IS NOT BOOKMARKED. This means that if you create an
1.103 + * annotation on an unvisited URI, it will get deleted when the browser
1.104 + * shuts down. Otherwise, URIs can exist in history as annotations but the
1.105 + * user has no way of knowing it, potentially violating their privacy
1.106 + * expectations about actions such as "Clear history".
1.107 + * If there is an important annotation that the user or extension wants to
1.108 + * keep, you should add a bookmark for the page and use an EXPIRE_NEVER
1.109 + * annotation. This will ensure the annotation exists until the item is
1.110 + * removed by the user.
1.111 + * See EXPIRE_* constants above for further information.
1.112 + *
1.113 + * The annotation "favicon" is special. Favicons are stored in the favicon
1.114 + * service, but are special cased in the protocol handler so they look like
1.115 + * annotations. Do not set favicons using this service, it will not work.
1.116 + *
1.117 + * Only C++ consumers may use the type-specific methods.
1.118 + *
1.119 + * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
1.120 + */
1.121 + void setPageAnnotation(in nsIURI aURI,
1.122 + in AUTF8String aName,
1.123 + in nsIVariant aValue,
1.124 + in long aFlags,
1.125 + in unsigned short aExpiration);
1.126 + void setItemAnnotation(in long long aItemId,
1.127 + in AUTF8String aName,
1.128 + in nsIVariant aValue,
1.129 + in long aFlags,
1.130 + in unsigned short aExpiration);
1.131 +
1.132 + /**
1.133 + * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
1.134 + */
1.135 + [noscript] void setPageAnnotationString(in nsIURI aURI,
1.136 + in AUTF8String aName,
1.137 + in AString aValue,
1.138 + in long aFlags,
1.139 + in unsigned short aExpiration);
1.140 + [noscript] void setItemAnnotationString(in long long aItemId,
1.141 + in AUTF8String aName,
1.142 + in AString aValue,
1.143 + in long aFlags,
1.144 + in unsigned short aExpiration);
1.145 +
1.146 + /**
1.147 + * Sets an annotation just like setAnnotationString, but takes an Int32 as
1.148 + * input.
1.149 + *
1.150 + * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
1.151 + */
1.152 + [noscript] void setPageAnnotationInt32(in nsIURI aURI,
1.153 + in AUTF8String aName,
1.154 + in long aValue,
1.155 + in long aFlags,
1.156 + in unsigned short aExpiration);
1.157 + [noscript] void setItemAnnotationInt32(in long long aItemId,
1.158 + in AUTF8String aName,
1.159 + in long aValue,
1.160 + in long aFlags,
1.161 + in unsigned short aExpiration);
1.162 +
1.163 + /**
1.164 + * Sets an annotation just like setAnnotationString, but takes an Int64 as
1.165 + * input.
1.166 + *
1.167 + * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
1.168 + */
1.169 + [noscript] void setPageAnnotationInt64(in nsIURI aURI,
1.170 + in AUTF8String aName,
1.171 + in long long aValue,
1.172 + in long aFlags,
1.173 + in unsigned short aExpiration);
1.174 + [noscript] void setItemAnnotationInt64(in long long aItemId,
1.175 + in AUTF8String aName,
1.176 + in long long aValue,
1.177 + in long aFlags,
1.178 + in unsigned short aExpiration);
1.179 +
1.180 + /**
1.181 + * Sets an annotation just like setAnnotationString, but takes a double as
1.182 + * input.
1.183 + *
1.184 + * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
1.185 + */
1.186 + [noscript] void setPageAnnotationDouble(in nsIURI aURI,
1.187 + in AUTF8String aName,
1.188 + in double aValue,
1.189 + in long aFlags,
1.190 + in unsigned short aExpiration);
1.191 + [noscript] void setItemAnnotationDouble(in long long aItemId,
1.192 + in AUTF8String aName,
1.193 + in double aValue,
1.194 + in long aFlags,
1.195 + in unsigned short aExpiration);
1.196 +
1.197 + /**
1.198 + * Retrieves the value of a given annotation. Throws an error if the
1.199 + * annotation does not exist. C++ consumers may use the type-specific
1.200 + * methods.
1.201 + *
1.202 + * The type-specific methods throw if the given annotation is set in
1.203 + * a different type.
1.204 + */
1.205 + nsIVariant getPageAnnotation(in nsIURI aURI,
1.206 + in AUTF8String aName);
1.207 + nsIVariant getItemAnnotation(in long long aItemId,
1.208 + in AUTF8String aName);
1.209 +
1.210 + /**
1.211 + * @see getPageAnnotation
1.212 + */
1.213 + [noscript] AString getPageAnnotationString(in nsIURI aURI,
1.214 + in AUTF8String aName);
1.215 + [noscript] AString getItemAnnotationString(in long long aItemId,
1.216 + in AUTF8String aName);
1.217 +
1.218 + /**
1.219 + * @see getPageAnnotation
1.220 + */
1.221 + [noscript] long getPageAnnotationInt32(in nsIURI aURI,
1.222 + in AUTF8String aName);
1.223 + [noscript] long getItemAnnotationInt32(in long long aItemId,
1.224 + in AUTF8String aName);
1.225 +
1.226 + /**
1.227 + * @see getPageAnnotation
1.228 + */
1.229 + [noscript] long long getPageAnnotationInt64(in nsIURI aURI,
1.230 + in AUTF8String aName);
1.231 + [noscript] long long getItemAnnotationInt64(in long long aItemId,
1.232 + in AUTF8String aName);
1.233 +
1.234 + /**
1.235 + * @see getPageAnnotation
1.236 + */
1.237 + [noscript] double getPageAnnotationDouble(in nsIURI aURI,
1.238 + in AUTF8String aName);
1.239 + [noscript] double getItemAnnotationDouble(in long long aItemId,
1.240 + in AUTF8String aName);
1.241 +
1.242 + /**
1.243 + * Retrieves info about an existing annotation.
1.244 + *
1.245 + * aType will be one of TYPE_* constansts above
1.246 + *
1.247 + * example JS:
1.248 + * var flags = {}, exp = {}, type = {};
1.249 + * annotator.getAnnotationInfo(myURI, "foo", flags, exp, type);
1.250 + * // now you can use 'exp.value' and 'flags.value'
1.251 + */
1.252 + void getPageAnnotationInfo(in nsIURI aURI,
1.253 + in AUTF8String aName,
1.254 + out int32_t aFlags,
1.255 + out unsigned short aExpiration,
1.256 + out unsigned short aType);
1.257 + void getItemAnnotationInfo(in long long aItemId,
1.258 + in AUTF8String aName,
1.259 + out long aFlags,
1.260 + out unsigned short aExpiration,
1.261 + out unsigned short aType);
1.262 +
1.263 + /**
1.264 + * Retrieves the type of an existing annotation
1.265 + * Use getAnnotationInfo if you need this along with the mime-type etc.
1.266 + *
1.267 + * @param aURI
1.268 + * the uri on which the annotation is set
1.269 + * @param aName
1.270 + * the annotation name
1.271 + * @return one of the TYPE_* constants above
1.272 + * @throws if the annotation is not set
1.273 + */
1.274 + uint16_t getPageAnnotationType(in nsIURI aURI,
1.275 + in AUTF8String aName);
1.276 + uint16_t getItemAnnotationType(in long long aItemId,
1.277 + in AUTF8String aName);
1.278 +
1.279 + /**
1.280 + * Returns a list of all URIs having a given annotation.
1.281 + */
1.282 + void getPagesWithAnnotation(
1.283 + in AUTF8String name,
1.284 + [optional] out unsigned long resultCount,
1.285 + [retval, array, size_is(resultCount)] out nsIURI results);
1.286 + void getItemsWithAnnotation(
1.287 + in AUTF8String name,
1.288 + [optional] out unsigned long resultCount,
1.289 + [retval, array, size_is(resultCount)] out long long results);
1.290 +
1.291 + /**
1.292 + * Returns a list of mozIAnnotation(s), having a given annotation name.
1.293 + *
1.294 + * @param name
1.295 + * The annotation to search for.
1.296 + * @return list of mozIAnnotation objects.
1.297 + */
1.298 + void getAnnotationsWithName(
1.299 + in AUTF8String name,
1.300 + [optional] out unsigned long count,
1.301 + [retval, array, size_is(count)] out mozIAnnotatedResult results);
1.302 +
1.303 + /**
1.304 + * Get the names of all annotations for this URI.
1.305 + *
1.306 + * example JS:
1.307 + * var annotations = annotator.getPageAnnotations(myURI, {});
1.308 + */
1.309 + void getPageAnnotationNames(
1.310 + in nsIURI aURI,
1.311 + [optional] out unsigned long count,
1.312 + [retval, array, size_is(count)] out nsIVariant result);
1.313 + void getItemAnnotationNames(
1.314 + in long long aItemId,
1.315 + [optional] out unsigned long count,
1.316 + [retval, array, size_is(count)] out nsIVariant result);
1.317 +
1.318 + /**
1.319 + * Test for annotation existence.
1.320 + */
1.321 + boolean pageHasAnnotation(in nsIURI aURI,
1.322 + in AUTF8String aName);
1.323 + boolean itemHasAnnotation(in long long aItemId,
1.324 + in AUTF8String aName);
1.325 +
1.326 + /**
1.327 + * Removes a specific annotation. Succeeds even if the annotation is
1.328 + * not found.
1.329 + */
1.330 + void removePageAnnotation(in nsIURI aURI,
1.331 + in AUTF8String aName);
1.332 + void removeItemAnnotation(in long long aItemId,
1.333 + in AUTF8String aName);
1.334 +
1.335 + /**
1.336 + * Removes all annotations for the given page/item.
1.337 + * We may want some other similar functions to get annotations with given
1.338 + * flags (once we have flags defined).
1.339 + */
1.340 + void removePageAnnotations(in nsIURI aURI);
1.341 + void removeItemAnnotations(in long long aItemId);
1.342 +
1.343 + /**
1.344 + * Copies all annotations from the source to the destination URI/item. If
1.345 + * the destination already has an annotation with the same name as one on
1.346 + * the source, it will be overwritten if aOverwriteDest is set. Otherwise,
1.347 + * the original annotation will be preferred.
1.348 + *
1.349 + * All the source annotations will stay as-is. If you don't want them
1.350 + * any more, use removePageAnnotations on that URI.
1.351 + */
1.352 + void copyPageAnnotations(in nsIURI aSourceURI,
1.353 + in nsIURI aDestURI,
1.354 + in boolean aOverwriteDest);
1.355 + void copyItemAnnotations(in long long aSourceItemId,
1.356 + in long long aDestItemId,
1.357 + in boolean aOverwriteDest);
1.358 +
1.359 + /**
1.360 + * Adds an annotation observer. The annotation service will keep an owning
1.361 + * reference to the observer object.
1.362 + */
1.363 + void addObserver(in nsIAnnotationObserver aObserver);
1.364 +
1.365 +
1.366 + /**
1.367 + * Removes an annotaton observer previously registered by addObserver.
1.368 + */
1.369 + void removeObserver(in nsIAnnotationObserver aObserver);
1.370 +};
1.371 +
1.372 +/**
1.373 + * Represents a place annotated with a given annotation. If a place has
1.374 + * multiple annotations, it can be represented by multiple
1.375 + * mozIAnnotatedResult(s).
1.376 + */
1.377 +[scriptable, uuid(81fd0188-db6a-492e-80b6-f6414913b396)]
1.378 +interface mozIAnnotatedResult : nsISupports
1.379 +{
1.380 + /**
1.381 + * The globally unique identifier of the place with this annotation.
1.382 + *
1.383 + * @note if itemId is valid this is the guid of the bookmark, otherwise
1.384 + * of the page.
1.385 + */
1.386 + readonly attribute AUTF8String guid;
1.387 +
1.388 + /**
1.389 + * The URI of the place with this annotation, if available, null otherwise.
1.390 + */
1.391 + readonly attribute nsIURI uri;
1.392 +
1.393 + /**
1.394 + * The bookmark id of the place with this annotation, if available,
1.395 + * -1 otherwise.
1.396 + *
1.397 + * @note if itemId is -1, it doesn't mean the page is not bookmarked, just
1.398 + * that this annotation is relative to the page, not to the bookmark.
1.399 + */
1.400 + readonly attribute long long itemId;
1.401 +
1.402 + /**
1.403 + * Name of the annotation.
1.404 + */
1.405 + readonly attribute AUTF8String annotationName;
1.406 +
1.407 + /**
1.408 + * Value of the annotation.
1.409 + */
1.410 + readonly attribute nsIVariant annotationValue;
1.411 +};
