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

394 lines
13 KiB
Plaintext

#include "nsISupports.idl"
interface nsIDOMDocument;
interface nsIDOMNode;
interface nsIURI;
interface nsISimpleEnumerator;
interface nsIMicrosummary;
[scriptable, uuid(560b0980-be95-47e9-81cc-4428c073127c)]
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 observed microsummary encounters an error during an update.
*
* @param microsummary
* the microsumary which could not be updated
*
*/
void onError(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(05b48344-d0a7-427e-934e-9a6e0d5ecced)]
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;
/**
* microsummary-generator equivalence test
* generators equal if their canonical locations equal, see uri attribute.
*/
boolean equals(in nsIMicrosummaryGenerator aOther);
// For generators installed by the user or bundled with the browser, the
// local URI points to the location of the local file containing the
// generator's XML.
readonly attribute nsIURI localURI;
// 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(6867dc21-077f-4462-937d-cd8b7c680e0c)]
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;
// Used when a site author has indicated that a microsummary (or an
// associated generator) will no longer be available.
readonly attribute boolean needsRemoval;
/**
* 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);
/**
* Microsummary equivalence test
* Microsummaries equal if they summarize the same page with the same
* microsummary-generator (see also nsIMicrosummaryGenerator::equals).
*
* Note: this method returns false if either objects don't have a generator
*/
boolean equals(in nsIMicrosummary aOther);
/**
* 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(D58143A2-74FA-4B13-94ED-113AF8936D80)]
interface nsIMicrosummaryService : nsISupports
{
/**
* Return a microsummary generator for the given URI.
*
* @param generatorURI
* the URI of the generator
*
* @returns an nsIMicrosummaryGenerator for the given URI.
*
*/
nsIMicrosummaryGenerator getGenerator(in nsIURI generatorURI);
/**
* 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 long long 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 long long bookmarkID);
/**
* Create a microsummary for a given page URI and generator URI.
*
* @param pageURI
* the URI of the page to be summarized
*
* @param generatorURI
* the URI of the microsummary generator
*
* @returns an nsIMicrosummary for the given page and generator URIs.
*
*/
nsIMicrosummary createMicrosummary(in nsIURI pageURI, in nsIURI generatorURI);
/**
* 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 long long 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 long long 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 long long 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 long long 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 long long bookmarkID);
};
[scriptable, uuid(f9e577a8-19d9-4ca0-a140-b9e43f014470)]
interface nsILiveTitleNotificationSubject : nsISupports
{
// The ID of the bookmark displaying this title.
// Note: in the old bookmarks code, this is an RDF resource. In Places
// it is currently a URI, but after the fix for bug 360133 lands it will
// become an integer.
readonly attribute long long bookmarkID;
// The microsummary being displayed as the live title for the bookmark.
// The actual value of the microsummary (i.e. the string that gets displayed
// to the user) is stored in the content property of this object.
readonly attribute nsIMicrosummary microsummary;
};