/Users/dietrich/moz/trunk/mozilla/toolkit/components/places/public/nsIAnnotationService.idl

Go to the documentation of this file.

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

interface nsIURI;
interface nsIVariant;

[scriptable, uuid(63fe98e0-6889-4c2c-ac9f-703e4bc25027)]
interface nsIAnnotationObserver : nsISupports
{
    void onPageAnnotationSet(in nsIURI aPage, in AUTF8String aName);
    void onItemAnnotationSet(in long long aItemId, in AUTF8String aName);

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

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

    [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);

    [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);

    [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);

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

    nsIVariant getPageAnnotation(in nsIURI aURI, in AUTF8String aName);
    nsIVariant getItemAnnotation(in long long aItemId, in AUTF8String aName);

    [noscript] AString getPageAnnotationString(in nsIURI aURI, in AUTF8String aName);
    [noscript] AString getItemAnnotationString(in long long aItemId, in AUTF8String aName);

    [noscript] long getPageAnnotationInt32(in nsIURI aURI, in AUTF8String aName);
    [noscript] long getItemAnnotationInt32(in long long aItemId, in AUTF8String aName);

    [noscript] long long getPageAnnotationInt64(in nsIURI aURI, in AUTF8String aName);
    [noscript] long long getItemAnnotationInt64(in long long aItemId, in AUTF8String aName);

    [noscript] double getPageAnnotationDouble(in nsIURI aURI, in AUTF8String aName);
    [noscript] double getItemAnnotationDouble(in long long aItemId, in AUTF8String aName);

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

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

    PRUint16 getPageAnnotationType(in nsIURI aURI, in AUTF8String aName);
    PRUint16 getItemAnnotationType(in long long aItemId, in AUTF8String aName);

    void getPagesWithAnnotation(in AUTF8String name,
      out unsigned long resultCount,
      [retval, array, size_is(resultCount)] out nsIURI results);
    void getItemsWithAnnotation(in AUTF8String name,
      out unsigned long resultCount,
      [retval, array, size_is(resultCount)] out long long results);

    void getPageAnnotationNames(in nsIURI aURI, out unsigned long count,
      [retval, array, size_is(count)] out nsIVariant result);
    void getItemAnnotationNames(in long long aItemId, out unsigned long count,
      [retval, array, size_is(count)] out nsIVariant result);

    boolean pageHasAnnotation(in nsIURI aURI, in AUTF8String aName);
    boolean itemHasAnnotation(in long long aItemId, in AUTF8String aName);

    void removePageAnnotation(in nsIURI aURI, in AUTF8String aName);
    void removeItemAnnotation(in long long aItemId, in AUTF8String aName);

    void removePageAnnotations(in nsIURI aURI);
    void removeItemAnnotations(in long long aItemId);

    void copyPageAnnotations(in nsIURI aSourceURI, in nsIURI aDestURI,
                             in boolean aOverwriteDest);
    void copyItemAnnotations(in long long aSourceItemId,
                             in long long aDestItemId,
                             in boolean aOverwriteDest);

    void addObserver(in nsIAnnotationObserver aObserver);


    void removeObserver(in nsIAnnotationObserver aObserver);

    nsIURI getAnnotationURI(in nsIURI aURI, in AUTF8String aName);
};

---