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 (07eb2cc7e1c3)

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
/* -*- 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);

    /**
     * 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);
};