Mozilla/mozilla/browser/components/microsummaries/public/nsIMicrosummaryService.idl

#include "nsISupports.idl"

interface nsIDOMNode;
interface nsIURI;
interface nsISimpleEnumerator;
interface nsIMicrosummary;

[scriptable, uuid(cb284a83-1ca5-4000-9841-ce345ce84915)]
interface nsIMicrosummaryObserver : nsISupports
{
    /**
     * Called when an observed microsummary updates its content.
     * Since an observer might watch multiple microsummaries at the same time,
     * the microsummary whose content has been updated gets passed
     * to this handler.
     * XXX Should this be onContentUpdated?
     *
     * @param microsummary
     *        the microsummary whose content has just been updated
     *
     */
    void onContentLoaded(in nsIMicrosummary microsummary);

    /**
     * Called when an element is appended to a microsummary set.
     * XXX Should this be in a separate nsICollectionObserver interface?
     *
     * @param microsummary
     *        the microsummary that has just been appended to the set
     *
     */
    void onElementAppended(in nsIMicrosummary microsummary);
};


[scriptable, uuid(ff3eba15-81de-4c24-bfcf-c8180dc3c00a)]
interface nsIMicrosummaryGenerator : nsISupports
{
    // An arbitrary descriptive name for this microsummary generator.
    readonly attribute AUTF8String name;

    // The canonical location and unique identifier of the generator.
    // It tells us where the generator comes from and where to go for updates.
    // For generators referenced by web pages via <link> tags, this URI
    // is the one specified by the tag.  For generators installed by users,
    // this URI is the remote location from which we installed the generator.
    // For generators bundled with the browser, this URI is a reference
    // to the latest version of this generator available on Mozilla Add-ons.
    readonly attribute nsIURI uri;

    // Whether or not this generator needs page content to generate
    // a microsummary. Microsummaries generated by XSLT templates need page
    // content, while those which represent the actual microsummary content
    // do not.
    readonly attribute boolean needsPageContent;

    /**
     * Generate a microsummary by processing the generator template
     * against the page content.  If a generator doesn't need content,
     * pass null as the parameter to this method.
     *
     * XXX In the future, this should support returning rich text content,
     * so perhaps we should make it return a DOM node now and have the caller
     * convert that to text if it doesn't support rich content.
     *
     * @param   pageContent
     *          the content of the page being summarized
     * @returns the text result of processing the template
     *
     */
    AString generateMicrosummary(in nsIDOMNode aPageContent);
};


[scriptable, uuid(f9d1a73c-e147-46f3-ba61-4f0bd33f5d47)]
interface nsIMicrosummary : nsISupports
{
    // the URI of the page being summarized
    readonly attribute nsIURI pageURI;

    // The URI of the generator that generates this microsummary.
    readonly attribute nsIURI generatorURI;

    // The generator that generates this microsummary.
    // Since generators can be remote resources, this may not always be available.
    attribute nsIMicrosummaryGenerator generator;

    // The content of the microsummary.
    // Since generators and pages can be remote resources, and we need them
    // to generate the content, this may not always be available.
    readonly attribute AString content;

    /**
     * Add a microsummary observer to this microsummary.
     *
     * @param observer
     *        the microsummary observer to add
     *
     */
    void addObserver(in nsIMicrosummaryObserver observer);

    /**
     * Remove a microsummary observer from this microsummary.
     *
     * @param observer
     *        the microsummary observer to remove
     *
     */
    void removeObserver(in nsIMicrosummaryObserver observer);

    /**
     * Update the microsummary, first loading its generator and page content
     * as necessary.  If you want know when a microsummary finishes updating,
     * add an observer before calling this method.
     *
     */
    void update();
};

[scriptable, uuid(7111e88d-fecd-4b17-b7a9-1fa74e23153f)]
interface nsIMicrosummarySet : nsISupports
{
    /**
     * Add a microsummary observer to this microsummary set.  Adding an observer
     * to a set is the equivalent of adding it to each constituent microsummary.
     *
     * @param observer
     *        the microsummary observer to add
     *
     */
    void addObserver(in nsIMicrosummaryObserver observer);

    /**
     * Remove a microsummary observer from this microsummary.
     *
     * @param observer
     *        the microsummary observer to remove
     *
     */
    void removeObserver(in nsIMicrosummaryObserver observer);

    /**
     * Retrieve a enumerator of microsummaries in the set.
     *
     * @returns an enumerator of nsIMicrosummary objects
     *
     */
    nsISimpleEnumerator Enumerate();
};


[scriptable, uuid(c5e9c390-beb0-4eb4-90ab-529efc817632)]
interface nsIMicrosummaryService : nsISupports
{
    /**
     * Install the microsummary generator from the resource at the supplied URI.
     * Callable by content via the addMicrosummaryGenerator() sidebar method.
     *
     * @param   generatorURI
     *          the URI of the resource providing the generator
     *
     */
    void addGenerator(in nsIURI generatorURI);

    /**
     * Get the set of microsummaries available for a given page.  The set
     * might change after this method returns, since this method will trigger
     * an asynchronous load of the page in question (if it isn't already loaded)
     * to see if it references any page-specific microsummaries.
     *
     * If the caller passes a bookmark ID, and one of the microsummaries
     * is the current one for the bookmark, this method will retrieve content
     * from the datastore for that microsummary, which is useful when callers
     * want to display a list of microsummaries for a page that isn't loaded,
     * and they want to display the actual content of the selected microsummary
     * immediately (rather than after the content is asynchronously loaded).
     *
     * @param   pageURI
     *          the URI of the page for which to retrieve available microsummaries
     *
     * @param   bookmarkID (optional)
     *          the ID of the bookmark for which this method is being called
     *
     * @returns an nsIMicrosummarySet of nsIMicrosummaries for the given page
     *
     */
    nsIMicrosummarySet getMicrosummaries(in nsIURI pageURI,
                                         in nsISupports bookmarkID);

    /**
     * Get the current microsummary for the given bookmark.
     *
     * @param   bookmarkID
     *          the bookmark for which to get the current microsummary
     *
     * @returns the current microsummary for the bookmark, or null
     *          if the bookmark does not have a current microsummary
     *
     */
    nsIMicrosummary getMicrosummary(in nsISupports bookmarkID);

    /**
     * Set the current microsummary for the given bookmark.
     *
     * @param   bookmarkID
     *          the bookmark for which to set the current microsummary
     *
     * @param   microsummary
     *          the microsummary to set as the current one
     *
     */
    void setMicrosummary(in nsISupports bookmarkID,
                         in nsIMicrosummary microsummary);

    /**
     * Remove the current microsummary for the given bookmark.
     *
     * @param   bookmarkID
     *          the bookmark for which to remove the current microsummary
     *
     */
    void removeMicrosummary(in nsISupports bookmarkID);

    /**
     * Whether or not the given bookmark has a current microsummary.
     *
     * @param   bookmarkID
     *          the bookmark for which to set the current microsummary
     *
     * @returns a boolean representing whether or not the given bookmark
     *          has a current microsummary
     *
     */
    boolean hasMicrosummary(in nsISupports bookmarkID);

    /**
     * Whether or not the given microsummary is the current microsummary
     * for the given bookmark.
     *
     * @param   bookmarkID
     *          the bookmark to check
     *
     * @param   microsummary
     *          the microsummary to check
     *
     * @returns whether or not the microsummary is the current one
     *          for the bookmark
     *
     */
    boolean isMicrosummary(in nsISupports bookmarkID,
                           in nsIMicrosummary microsummary);
};