RetroZilla/browser/components/places/public/nsIAnnotationService.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is Annotation code
 *
 * The Initial Developer of the Original Code is
 * Google Inc.
 * Portions created by the Initial Developer are Copyright (C) 2005
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Brett Wilson <brettw@gmail.com>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"

%{C++
#include "nsTArray.h"
#include "nsCOMArray.h"
#include "nsString.h"
%}

interface nsIURI;
interface nsIVariant;

[ptr] native CStringArray(nsTArray<nsCString>);
[ptr] native URIArray(nsCOMArray<nsIURI>);

[scriptable, uuid(d41c9510-2377-4728-b275-bdad6a0521f8)]
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 onAnnotationSet(in nsIURI aURI, 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 onAnnotationRemoved(in nsIURI aURI, in AUTF8String aName);
};

[scriptable, uuid(a857c97f-7705-4376-b374-bd8799f69d51)]
interface nsIAnnotationService : nsISupports
{
    /**
     * Valid values for aExpiration, which sets the expiration policy for your
     * annotation. These times are measured since the last visit date of the
     * page in question. This means that if you set an annotation with anything
     * but session expiration, it will not expire so long as the user keeps
     * visiting the page from time to time.
     */

    /* EXPIRATION IS CURRENTLY UNIMPLEMENTED. This is here as a proposed
       expiration policy. May be changed. Currently, use 0 for expiration.
     */
      // For temporary stuff that can be discarded when the user exists
    const PRInt32 EXPIRE_SESSION = 0;

      // for short-lived temporary data that you still want to outlast a session
    const PRInt32 EXPIRE_DAYS = 1;

      // for general page settings, things the user is interested in seeing
      // if they come back to this page some time in the future.
    const PRInt32 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 much other annotation,
      // the positions of things, or other stuff you create, so put that in
      // the weeks policy.
    const PRInt32 EXPIRE_MONTHS = 3;

      // For small, user-entered data like notes that should never expire.
    const PRInt32 EXPIRE_NEVER = 4;

    /**
     * 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 ANNOTATIONS WILL GET DELETED WHEN THE PAGE IS REMOVED FROM
     * HISTORY, regardless of expiration date. This means that if you create an
     * annotation on a random unvisited URI, it will get deleted when the
     * browser shuts down.  Otherwise, things 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 wants to keep, you should
     * make sure that URL is bookmarked. This will ensure the item is never
     * completely deleted from the history database.
     *
     * 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.
     */
    void setAnnotationString(in nsIURI aURI, in AUTF8String aName,
                             in AString aValue, in PRInt32 aFlags,
                             in PRInt32 aExpiration);

    /**
     * Sets an annotation just like setAnnotationString, but takes an Int32 as
     * input.
     */
    void setAnnotationInt32(in nsIURI aURI, in AUTF8String aName,
                            in PRInt32 aValue, in PRInt32 aFlags,
                            in PRInt32 aExpiration);

    /**
     * Sets an annotation just like setAnnotationString, but takes an Int64 as
     * input.
     */
    void setAnnotationInt64(in nsIURI aURI, in AUTF8String aName,
                            in PRInt64 aValue, in PRInt32 aFlags,
                            in PRInt32 aExpiration);

    /**
     * Sets an annotation just like setAnnotationString, but takes a double as
     * input.
     */
    void setAnnotationDouble(in nsIURI aURI, in AUTF8String aName,
                             in double aValue, in PRInt32 aFlags,
                             in PRInt32 aExpiration);

    /*
     * Sets an annotation just like setAnnotationString, but takes binary data
     * as input. You MUST supply a valid MIME type.
     */
    void setAnnotationBinary(in nsIURI aURI, in AUTF8String aName,
                             [const,array,size_is(aDataLen)] in octet aData,
                             in PRUint32 aDataLen, in AUTF8String aMimeType,
                             in PRInt32 aFlags, in PRInt32 aExpiration);

    /**
     * Retrieves the string value of a given annotation. Throws an error if the
     * annotation does not exist. If the annotation was set as a different
     * type than you are retrieving it as, the value will be converted as best
     * as we can. You aren't always guaranteed a good conversion, however,
     * and errors will not be thrown in this case. (For example, doubles will
     * lose precision when stringified.)
     */
    AString getAnnotationString(in nsIURI aURI, in AUTF8String aName);

    /**
     * Same as getAnnotationString but for ints. If the value doesn't look like
     * an int, returns 0. (this is current sqlite behavior when asking for an
     * int when there is not one, it will possibly change in the future if we
     * start caching stuff).
     */
    PRInt32 getAnnotationInt32(in nsIURI aURI, in AUTF8String aName);

    /**
     * Same as getAnnotationString for Int64s. If the value doesn't look like
     * an int, returns 0. (this is current sqlite behavior when asking for an
     * int when there is not one, it will possibly change in the future if we
     * start caching stuff).
     */
    PRInt64 getAnnotationInt64(in nsIURI aURI, in AUTF8String aName);

    /**
     * Same as getAnnotationString but returns a double-precision float. If the
     * value doesn't look like an float, returns 0. (this is current sqlite
     * behavior when asking for an number when there is not one, it will
     * possibly change in the future if we start caching stuff).
     */
    double getAnnotationDouble(in nsIURI aURI, in AUTF8String aName);

    /**
     * Same as getAnnotationString but for binary data. This also returns the
     * MIME type.
     */
    void getAnnotationBinary(in nsIURI aURI, in AUTF8String aName,
                             [array,size_is(aDataLen)] out octet aData,
                             out PRUint32 aDataLen,
                             out AUTF8String aMimeType);

    /**
     * Retrieves info about an existing annotation. aMimeType will be empty
     * if the value was not binary data.
     *
     * aStorageType will be one of mozIStorageValueArray.VALUE_TYPE_* and
     * indicates how the value is stored (if you want to determine whether
     * the data is binary, etc.)
     *
     * example JS:
     *   var flags = {}, exp = {}, mimeType = {};
     *   annotator.getAnnotationInfo(myURI, "foo", flags, exp, mimeType);
     *   // now you can use 'exp.value' and 'flags.value'
     */
    void getAnnotationInfo(in nsIURI aURI, in AUTF8String aName,
                           out PRInt32 aFlags, out PRInt32 aExpiration,
                           out AUTF8String aMimeType, out PRInt32 aStorageType);

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

    /**
     * COMArray version of getPagesWithAnnotation for easier memory
     * management from C++ code;
     */
    [noscript] void GetPagesWithAnnotationCOMArray(in AUTF8String aName,
                                                 in URIArray aResults);

    /**
     * Get the names of all annotations for this URI.
     *
     * example JS:
     *   var annotations = annotator.getPageAnnotations(myURI, {});
     * You probably don't want to use this from C++, use
     * GetPageAnnotationsTArray instead.
     */
    void getPageAnnotationNames(in nsIURI aURI, out PRUint32 count,
      [retval, array, size_is(count)] out nsIVariant result);

    /**
     * TArray version of getPageAnnotationNames for ease of use in C++ code.
     */
    [noscript] void GetPageAnnotationNamesTArray(in nsIURI aURI, in CStringArray aResult);

    /**
     * Test for annotation existance.
     */
    boolean hasAnnotation(in nsIURI aURI, in AUTF8String aName);

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

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

    /**
     * Copies all annotations from the source to the destination URI. 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 destination URIs 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 copyAnnotations(in nsIURI aSourceURI, in nsIURI aDestURI,
                         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);
};