DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (c01d7a2e7297)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
/* -*- 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);
};