Places/AsyncAPIsForSync/History

Tracked by: bug 606966

Description of Sync's history records: https://wiki.mozilla.org/Labs/Weave/Developer/BrowserObjects#history

Read

We already roll our own async SQL queries to fetch the metadata for a history entry and its visits (two queries). We could push this down to Places, but given that we already do the right thing here, it probably has low priority.

Write

Right now call nsINavHistoryService::addVisit() for each visit in a history record that doesn't exist locally yet and then nsINavHistoryService::setPageTitle() to set the page title. As discussed in https://bugzilla.mozilla.org/show_bug.cgi?id=606966#c14, an API that would allow us to pass in the page title and a list of visits would be great. It would asynchronously set the page title and add all the visits (unless they exist already)

Detailed History Proposal

This proposal is considered to be stable.

nsIVisitInfo

interface nsIVisitInfo : nsISupports
{
  // moz_historyvisits.id
  readonly long long id;
  readonly PRTime date;
  readonly long transitionType;
  // optional (could be null)
  readonly nsIURI referrer;
  readonly long long sessionId;
}

This is a new interface that describes a visit for a place (that is described by nsIPlaceInfo).

nsIPlaceInfo

interface nsIPlaceInfo : nsISupports
{
  // moz_places.id
  readonly long long id;
  readonly nsIURI uri;
  readonly AString title;
  readonly ACString guid;
  readonly long long frecency;

  /**
   * An array of nsIVisitInfo objects for the place.
   */
  readonly nsIVariant visits;
}

This is a new interface that describes a place (stored in moz_places). This will currently only need to be implemented for nsIPlaceInfoCallback.

The visits attribute can contain multiple visits the nsIPlaceInfo is passed into updatePlace or updatePlaces.

The visits attribute will only ever have one entry when it is used with nsIPlaceInfoCallback.

nsIPlaceInfoCallback

interface nsIPlaceInfoCallback : nsISupports
{
  /**
   * Called when one of the visit methods has added a visit.
   *
   * @param aResultCode
   *        nsresult of the visit addition.  Success indicated by Components.isSuccessCode(aResultCode).
   * @param aPlaceInfo
   *        The information about the visit.
   */
  void onComplete(in nsresult aResultCode,
                  in nsIPlaceInfo aPlaceInfo);
}

updatePlace

/**
 * Adds a set of visits for a place info object.  The callback is called once for each visit.  Ignores duplicates.  Also updates the guid or title.
 *
 * @param aPlaceInfo
 *        Information about the place to add.
 * @param [optional] aCallback
 *        Callback to be notified for each visit.
 */
void updatePlace(in nsIPlaceInfo aPlaceInfo,
                 [optional] in nsIVisitInfoCallback aCallback);

Method for adding or updating a place with visits to the database. If a place already exists, each visit is added to the database (without duplication). If the place does not exists, it is first added, and then each visit is added (duplication does not need to be checked in this case). The callback (if provided) is called for each successful visit addition.

Required fields for inserting a new place:

• uri
• visits.length > 0

Required fields for updating a place (only one needed):

• id
• guid

Required fields for each visit (updating a place or inserting):

• date
• transition type

This must also notify the appropriate events to the observers listening with a nsINavHistoryObserver.

updatePlaces

/**
 * Just like updatePlaceAndAddVisits.
 *
 * @param aPlaceInfos
 *        Information about the places to add.
 * @param aPlaces
 *        The number of aPlaceInfos.
 * @param [optional] aCallback
 *        Callback to be notified for each visit.
 */
void updatePlaces([array, size_is(aPlaces)] in nsIPlaceInfo aPlaceInfos,
                  in unsigned long aPlaces,
                  [optional] in nsIVisitInfoCallback aCallback);

Just like updatePlace but with one additional requirement: This must dispatch the appropriate batch notification when aPlaces > 1 (nsINavHistoryObserver::on[Begin|End]UpdateBatch)