Usage of nsIMicrosummary Interface

 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)

 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)

 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)

 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)

 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)

 Called when an observed microsummary encounters an error during an update.
 
 @param microsummary
        the microsummary which could not be updated

void onError(in nsIMicrosummary microsummary)

 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)

 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)

 Transaction for editing a bookmark's microsummary.

 @param aBookmarkId
        id of the bookmark to edit
 @param aNewMicrosummary
        new microsummary for the bookmark
 @returns nsITransaction object

nsITransaction editBookmarkMicrosummary(in long long aBookmarkId, in nsIMicrosummary aNewMicrosummary)