Services/Sync/Features/Addon Sync: Difference between revisions

Jump to navigation Jump to search

Services/Sync/Features/Addon Sync (view source)

Revision as of 22:47, 30 August 2011

86 bytes removed ,  30 August 2011
rewrite addonmanager api changes
No edit summary
(rewrite addonmanager api changes)
Line 30: Line 30:
For add-on objects, providers wishing to opt in to Sync will expose the following read-only, optional properties:
For add-on objects, providers wishing to opt in to Sync will expose the following read-only, optional properties:


; syncData : a string that describes data necessary to synchronize the add-on between clients. The format of the string is not defined, and is opaque to Sync code. A JSON representation of an object might be a good choice, to hold the data needed by the add-ons manager to install/uninstall an addon.
; syncData : a string that describes data necessary to synchronize the add-on between clients. The format of the string is opaque to Sync code. From the perspective of add-on providers, it should be a JSON object with a *type* field that is used to route it to the proper provider.


; syncGUID : a GUID used to identify this add-on across Sync client instances. The GUID should be generated using Utils.makeGUID() from the Sync code. It is basically a Base64-encoded representation of 9 random bytes.
; syncGUID : a GUID used to identify this add-on across Sync client instances. The GUID should be generated using Utils.makeGUID() from the Sync code. It is basically a Base64-encoded representation of 9 random bytes.
Line 40: Line 40:
; getAddonBySyncGUID(syncGUID, callback) : Obtain an add-on from its Sync GUID. Calls the supplied function when that add-on is retrieved. The callback receives null on unknown add-on or the add-on object (generated from the underlying provider) on success.
; getAddonBySyncGUID(syncGUID, callback) : Obtain an add-on from its Sync GUID. Calls the supplied function when that add-on is retrieved. The callback receives null on unknown add-on or the add-on object (generated from the underlying provider) on success.


; installOrUpdateAddonFromSyncData(syncData, syncGUID, callbackObj) : Installs an add-on from sync data or updates the add-on so it has the information specified. Receives the data from the original add-on, the GUID it should be installed with, and an object describing callbacks to be invoked when specific events occurs. The manager will try to obtain an install record and then execute the install. The callbackObj contains the optional keys *onFailure*, *onInstall*, and *onNewSyncGUID* which can be functions that are called when those events occur. Each function receives *syncData* and *syncGUID* as their first arguments. *onInstall* will additionally receive the newly-created (or existing) add-on record and a boolean indicating whether a restart is required. *onNewSyncGUID* will receive as a 3rd parameter the new syncGUID for the already-installed add-on. As inferred from the callback definition, the function must be able to detect existing add-ons from the *syncData* and update the *syncGUID* of that add-on to the value specified.  
; applySyncDataRecords(records, callbackObj) : This applies an array of records that contain add-on metadata and makes the current state of the world agree with that data as much as possible.


; uninstallAddonBySyncGUID(syncGUID, callbackObj) : Uninstalls an add-on specified by its syncGUID. The callbackObj has the optional keys *onSuccess* and *onFailure*. Each receives as an argument the passed *syncGUID*.
The callbackObj is an object containing the following optional keys:


Both of these APIs will require the AddonManager to have an additional relationship with the add-on providers (via APIs). The providers will need to provide a routine to install add-ons from *syncData* instances. And, the AddonManager will need to know how to call into these.
*onSuccess - Invoked when an individual record is processed successfully. Arguments are the record itself.
*onFailure - Invoked when an individual record could not be processed successfully. Arguments are the record itself.
*onFinished - Invoked when all records have finished processing.
 
Each record is an object containing the following keys:
 
* syncGUID (required) - The Sync GUID for this record
* syncData (optional) - The .syncData field from an add-on
* isDeleted (optional) - If evaluates to true, indicates that the record was deleted. Application of this record should involve trying to delete this add-on if present or no-op if not present.
 
The implementation of applySyncDataRecords() will resemble the following pseudocode:
 
foreach record in records:
  if record.isDeleted:
    found = this.getAddonBySyncGUID(record.syncGUID)
    if found:
      this.deleteAddon(found)
   
    callbackObj.onSuccess(record)
    continue
 
  existing = this.getExistingAddonBySyncData(record.syncData)
  if existing:
    existing.merge(record.syncData)
  else:
    this.installAddonFromSyncData(syncGUID, syncData)
 
  // call onSuccess on onFailure depending on result of above
 
callbackObj.onFinished()


The add-ons Sync engine will discover the set of add-ons that can be synced via the following procedure:
The add-ons Sync engine will discover the set of add-ons that can be synced via the following procedure:
Gszorc
canmove, Confirmed users
409

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/344963"

Navigation menu