RetroZilla/browser/components/microsummaries/public/nsIMicrosummaryService.idl

321 lines
11 KiB
Plaintext
Raw Normal View History

2015-10-21 05:03:22 +02:00
#include "nsISupports.idl"
interface nsIDOMDocument;
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(67ffe6b0-d4db-485c-ba20-5e2e8319b78d)]
interface nsIMicrosummaryGenerator : nsISupports
{
// Has the generator itself, which may be a remote resource, been loaded.
readonly attribute boolean loaded;
// 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 URL specified by the tag.
//
// For generators installed via nsSidebar::addMicrosummaryGenerator,
// this URI is a URN of the form urn:source:<url>, where <url> is the
// remote location from which we installed the generator.
//
// For generators installed via some other mechanism (f.e. an extension
// that dynamically creates generators), this URI is a URN in a form
// of the extension's own choosing, with the only restriction being that
// the URI be globally unique. To ensure this, we recommend that such
// extensions incorporate UUIDs created by nsUUIDGenerator into the URNs
// of the generators they create.
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);
/**
* Calculate the interval until the microsummary should be updated for
* the next time, depending on the page content. If the generator doesn't
* specify an interval, null is returned.
*
* @param pageContent
* the content of the page being summarized
* @returns the interval in milliseconds until the next update request
*
*/
long calculateUpdateInterval(in nsIDOMNode aPageContent);
};
[scriptable, uuid(1b1f232d-e65f-446a-9984-786578526072)]
interface nsIMicrosummary : nsISupports
{
// the URI of the page being summarized
readonly attribute nsIURI pageURI;
// The generator that generates this microsummary. May need to be loaded.
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;
// The minimum interval after which this microsummary would like to be refreshed
// (or null if it doesn't care).
readonly attribute long updateInterval;
/**
* 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(edec7c28-4b06-4692-842f-8bf238e61ac1)]
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);
/**
* Install the microsummary generator in the given XML definition.
*
* @param xmlDefinition
* an nsIDOMDocument XML document defining the generator
*
* @returns the newly-installed nsIMicrosummaryGenerator object
*
*/
nsIMicrosummaryGenerator installGenerator(in nsIDOMDocument xmlDefinition);
/**
* Get the set of bookmarks with microsummaries.
*
* In the old RDF-based bookmarks datastore, bookmark IDs are nsIRDFResource
* objects. In the new Places-based datastore, they are nsIURI objects.
*
* @returns an nsISimpleEnumerator enumeration of bookmark IDs
*
*/
nsISimpleEnumerator getBookmarks();
/**
* 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);
/**
* Refresh a microsummary, updating its value in the datastore and UI.
* If this method can refresh the microsummary instantly, it will.
* Otherwise, it'll asynchronously download the necessary information
* (the generator and/or page) before refreshing the microsummary.
*
* Callers should check the "content" property of the returned microsummary
* object to distinguish between sync and async refreshes. If its value
* is "null", then it's an async refresh, and the caller should register
* itself as an nsIMicrosummaryObserver via nsIMicrosummary.addObserver()
* to find out when the refresh completes.
*
* @param bookmarkID
* the bookmark whose microsummary is being refreshed
*
* @returns the microsummary being refreshed
*
*/
nsIMicrosummary refreshMicrosummary(in nsISupports bookmarkID);
};