gecko/toolkit/components/places/nsIAnnotationService.idl

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

[scriptable, uuid(63fe98e0-6889-4c2c-ac9f-703e4bc25027)]
interface nsIAnnotationObserver : nsISupports
{
    /**
     * Called when an annotation value is set. It could be a new annotation,
     * or it could be a new value for an existing annotation.
     */
    void onPageAnnotationSet(in nsIURI aPage,
                             in AUTF8String aName);
    void onItemAnnotationSet(in long long aItemId,
                             in AUTF8String aName);

    /**
     * Called when an annotation is deleted. If aName is empty, then ALL
     * annotations for the given URI have been deleted. This is not called when
     * annotations are expired (normally happens when the app exits).
     */
    void onPageAnnotationRemoved(in nsIURI aURI,
                                 in AUTF8String aName);
    void onItemAnnotationRemoved(in long long aItemId,
                                 in AUTF8String aName);
};

[scriptable, uuid(ba249b58-346f-42a9-a393-203ae34ec6c4)]
interface nsIAnnotationService : nsISupports
{
    /**
     * Valid values for aExpiration, which sets the expiration policy for your
     * annotation. The times for the days, weeks and months policies are
     * measured since the last visit date of the page in question. These 
     * will not expire so long as the user keeps visiting the page from time
     * to time.
     */

    // For temporary data that can be discarded when the user exits.
    // Removed at application exit.
    const unsigned short EXPIRE_SESSION = 0;

    // NOTE: 1 is skipped due to its temporary use as EXPIRE_NEVER in bug #319455.

    // For general page settings, things the user is interested in seeing
    // if they come back to this page some time in the near future.
    // Removed at 30 days. 
    const unsigned short EXPIRE_WEEKS = 2;

    // Something that the user will be interested in seeing in their
    // history like favicons. If they haven't visited a page in a couple
    // of months, they probably aren't interested in many other annotations,
    // the positions of things, or other stuff you create, so put that in
    // the weeks policy.
    // Removed at 180 days.
    const unsigned short EXPIRE_MONTHS = 3;

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

    // For annotations that only live as long as the URI has visits.
    // Valid only for page annotations.
    const unsigned short EXPIRE_WITH_HISTORY = 5;

    // For short-lived temporary data that you still want to outlast a session.
    // Removed at 7 days.
    const unsigned short EXPIRE_DAYS = 6;

    // type constants
    const unsigned short TYPE_INT32  = 1;
    const unsigned short TYPE_DOUBLE = 2;
    const unsigned short TYPE_STRING = 3;
    const unsigned short TYPE_BINARY = 4;
    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.
     *
     * NOTE: ALL PAGE ANNOTATIONS WILL GET DELETED WHEN THE PAGE IS REMOVED FROM
     * HISTORY IF THE PAGE IS NOT BOOKMARKED. This means that if you create an
     * annotation on an unvisited URI, it will get deleted when the browser
     * shuts down. Otherwise, URIs can exist in history as annotations but the
     * user has no way of knowing it, potentially violating their privacy
     * expectations about actions such as "Clear history".
     * If there is an important annotation that the user or extension wants to
     * keep, you should add a bookmark for the page and use an EXPIRE_NEVER
     * annotation.  This will ensure the annotation exists until the item is
     * removed by the user.
     * See EXPIRE_* constants above for further information.
     *
     * 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.
     *
     * Binary annotations should be set using
     * setItemAnnotationBinary/setPageAnnotationBinary. For other types, only
     * C++ consumers may use the type-specific methods.
     *
     * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
     */
    void setPageAnnotation(in nsIURI aURI,
                           in AUTF8String aName,
                           in nsIVariant aValue,
                           in long aFlags,
                           in unsigned short aExpiration);
    void setItemAnnotation(in long long aItemId,
                           in AUTF8String aName,
                           in nsIVariant aValue,
                           in long aFlags,
                           in unsigned short aExpiration);

    /**
     * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
     */
    [noscript] void setPageAnnotationString(in nsIURI aURI,
                                            in AUTF8String aName,
                                            in AString aValue,
                                            in long aFlags,
                                            in unsigned short aExpiration);
    [noscript] void setItemAnnotationString(in long long aItemId,
                                            in AUTF8String aName,
                                            in AString aValue,
                                            in long aFlags,
                                            in unsigned short aExpiration);

    /**
     * Sets an annotation just like setAnnotationString, but takes an Int32 as
     * input.
     *
     * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
     */
    [noscript] void setPageAnnotationInt32(in nsIURI aURI,
                                           in AUTF8String aName,
                                           in long aValue,
                                           in long aFlags,
                                           in unsigned short aExpiration);
    [noscript] void setItemAnnotationInt32(in long long aItemId,
                                           in AUTF8String aName,
                                           in long aValue,
                                           in long aFlags,
                                           in unsigned short aExpiration);

    /**
     * Sets an annotation just like setAnnotationString, but takes an Int64 as
     * input.
     *
     * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
     */
    [noscript] void setPageAnnotationInt64(in nsIURI aURI,
                                           in AUTF8String aName,
                                           in long long aValue,
                                           in long aFlags,
                                           in unsigned short aExpiration);
    [noscript] void setItemAnnotationInt64(in long long aItemId,
                                           in AUTF8String aName,
                                           in long long aValue,
                                           in long aFlags,
                                           in unsigned short aExpiration);

    /**
     * Sets an annotation just like setAnnotationString, but takes a double as
     * input.
     *
     * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
     */
    [noscript] void setPageAnnotationDouble(in nsIURI aURI,
                                            in AUTF8String aName,
                                            in double aValue,
                                            in long aFlags,
                                            in unsigned short aExpiration);
    [noscript] void setItemAnnotationDouble(in long long aItemId,
                                            in AUTF8String aName,
                                            in double aValue,
                                            in long aFlags,
                                            in unsigned short aExpiration);
    /**
     * Sets an annotation just like setAnnotationString, but takes binary data
     * as input. You MUST supply a valid MIME type.
     *
     * @throws NS_ERROR_ILLEGAL_VALUE if the page or the bookmark doesn't exist.
     */
    void setPageAnnotationBinary(in nsIURI aURI, in AUTF8String aName,
                                 [const,array,size_is(aDataLen)] in octet aData,
                                 in unsigned long aDataLen,
                                 in AUTF8String aMimeType,
                                 in long aFlags,
                                 in unsigned short aExpiration);
    void setItemAnnotationBinary(in long long aItemId, in AUTF8String aName,
                                 [const,array,size_is(aDataLen)] in octet aData,
                                 in unsigned long aDataLen,
                                 in AUTF8String aMimeType,
                                 in long aFlags,
                                 in unsigned short aExpiration);

    /**
     * Retrieves the value of a given annotation. Throws an error if the
     * annotation does not exist. Throws for binary annotations, for which
     * getPageAnnotationBinary/getItemAnnotationBinary should be used. C++
     * consumers may use the type-specific methods.
     *
     * The type-specific methods throw if the given annotation is set in
     * a different type.
     */
    nsIVariant getPageAnnotation(in nsIURI aURI,
                                 in AUTF8String aName);
    nsIVariant getItemAnnotation(in long long aItemId,
                                 in AUTF8String aName);

    /**
     * @see getPageAnnotation
     */
    [noscript] AString getPageAnnotationString(in nsIURI aURI,
                                               in AUTF8String aName);
    [noscript] AString getItemAnnotationString(in long long aItemId,
                                               in AUTF8String aName);

    /**
     * @see getPageAnnotation
     */
    [noscript] long getPageAnnotationInt32(in nsIURI aURI,
                                           in AUTF8String aName);
    [noscript] long getItemAnnotationInt32(in long long aItemId,
                                           in AUTF8String aName);

    /**
     * @see getPageAnnotation
     */
    [noscript] long long getPageAnnotationInt64(in nsIURI aURI,
                                                in AUTF8String aName);
    [noscript] long long getItemAnnotationInt64(in long long aItemId,
                                                in AUTF8String aName);

    /**
     * @see getPageAnnotation
     */
    [noscript] double getPageAnnotationDouble(in nsIURI aURI,
                                              in AUTF8String aName);
    [noscript] double getItemAnnotationDouble(in long long aItemId,
                                              in AUTF8String aName);

    /**
     * @see getPageAnnotation. This also returns the
     * MIME type.
     */
    void getPageAnnotationBinary(in nsIURI aURI,
                                 in AUTF8String aName,
                                 [array,size_is(aDataLen)] out octet aData,
                                 out unsigned long aDataLen,
                                 out AUTF8String aMimeType);
    void getItemAnnotationBinary(in long long aItemId,
                                 in AUTF8String aName,
                                 [array,size_is(aDataLen)] out octet aData,
                                 out unsigned long aDataLen,
                                 out AUTF8String aMimeType);

    /**
     * Retrieves info about an existing annotation. aMimeType will be empty
     * if the value was not binary data.
     *
     * aType will be one of TYPE_* constansts above
     *
     * example JS:
     *   var flags = {}, exp = {}, mimeType = {};
     *   annotator.getAnnotationInfo(myURI, "foo", flags, exp, mimeType);
     *   // now you can use 'exp.value' and 'flags.value'
     */
    void getPageAnnotationInfo(in nsIURI aURI,
                               in AUTF8String aName,
                               out PRInt32 aFlags,
                               out unsigned short aExpiration,
                               out AUTF8String aMimeType,
                               out unsigned short aType);
    void getItemAnnotationInfo(in long long aItemId,
                               in AUTF8String aName,
                               out long aFlags,
                               out unsigned short aExpiration,
                               out AUTF8String aMimeType,
                               out unsigned short aType);

    /**
     * Retrieves the type of an existing annotation
     * Use getAnnotationInfo if you need this along with the mime-type etc.
     *
     * @param aURI
     *        the uri on which the annotation is set
     * @param aName
     *        the annotation name
     * @return one of the TYPE_* constants above
     * @throws if the annotation is not set
     */
    PRUint16 getPageAnnotationType(in nsIURI aURI,
                                   in AUTF8String aName);
    PRUint16 getItemAnnotationType(in long long aItemId,
                                   in AUTF8String aName);

    /**
     * Returns a list of all URIs having a given annotation.
     */
    void getPagesWithAnnotation(
      in AUTF8String name,
      [optional] out unsigned long resultCount,
      [retval, array, size_is(resultCount)] out nsIURI results);
    void getItemsWithAnnotation(
      in AUTF8String name,
      [optional] out unsigned long resultCount,
      [retval, array, size_is(resultCount)] out long long results);

    /**
     * Get the names of all annotations for this URI.
     *
     * example JS:
     *   var annotations = annotator.getPageAnnotations(myURI, {});
     */
    void getPageAnnotationNames(
      in nsIURI aURI,
      [optional] out unsigned long count,
      [retval, array, size_is(count)] out nsIVariant result);
    void getItemAnnotationNames(
      in long long aItemId,
      [optional] out unsigned long count,
      [retval, array, size_is(count)] out nsIVariant result);

    /**
     * Test for annotation existence.
     */
    boolean pageHasAnnotation(in nsIURI aURI,
                              in AUTF8String aName);
    boolean itemHasAnnotation(in long long aItemId,
                              in AUTF8String aName);

    /**
     * Removes a specific annotation. Succeeds even if the annotation is
     * not found.
     */
    void removePageAnnotation(in nsIURI aURI,
                              in AUTF8String aName);
    void removeItemAnnotation(in long long aItemId,
                              in AUTF8String aName);

    /**
     * Removes all annotations for the given page/item.
     * We may want some other similar functions to get annotations with given
     * flags (once we have flags defined).
     */
    void removePageAnnotations(in nsIURI aURI);
    void removeItemAnnotations(in long long aItemId);

    /**
     * Copies all annotations from the source to the destination URI/item. If
     * the destination already has an annotation with the same name as one on
     * the source, it will be overwritten if aOverwriteDest is set. Otherwise,
     * the original annotation will be preferred.
     *
     * All the source annotations will stay as-is. If you don't want them
     * any more, use removePageAnnotations on that URI.
     */
    void copyPageAnnotations(in nsIURI aSourceURI,
                             in nsIURI aDestURI,
                             in boolean aOverwriteDest);
    void copyItemAnnotations(in long long aSourceItemId,
                             in long long aDestItemId,
                             in boolean aOverwriteDest);

    /**
     * Adds an annotation observer. The annotation service will keep an owning
     * reference to the observer object.
     */
    void addObserver(in nsIAnnotationObserver aObserver);


    /**
     * Removes an annotaton observer previously registered by addObserver.
     */
    void removeObserver(in nsIAnnotationObserver aObserver);

    /**
     * Returns a URI that can be used to access the given binary annotation.
     * This function does NOT check that the annotation exists. Also, note that
     * you can only load URIs for annotations that have have a valid MIME type
     * set by setAnnotationBinary. No non-URI valid chars in name, especially
     * colon, which will mess up parsing.
     */
    nsIURI getAnnotationURI(in nsIURI aURI,
                            in AUTF8String aName);
};