/*
 * BEGIN FLOCK GPL
 *
 * Copyright Flock Inc. 2005-2009
 * http://flock.com
 *
 * This file may be used under the terms of the
 * GNU General Public License Version 2 or later (the "GPL"),
 * http://www.gnu.org/licenses/gpl.html
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * END FLOCK GPL
 */

#include "nsISupports.idl"
#include "nsISupportsArray.idl"


[scriptable, uuid(5F525135-0DBD-4613-A705-4BBE47EAC91B)]
interface flockIMigrationProgressListener : nsISupports {
  void onUpdate(in long percent, in AUTF8String message);
};


[scriptable, uuid(85b52366-924b-4170-9327-f6001ec65153)]
interface flockIMigrationManager : nsISupports {
  nsISupportsArray setup(in string oldVersion);
};


[scriptable, uuid(0f283018-197e-417f-a823-00af7c085dd6)]
interface flockIMigratable : nsISupports {
  /**
   * UI display name for this migration step.
   */
  readonly attribute string migrationName;

  /**
   * Called to test whether this service needs any migration processing to
   * update from the indicated version.
   *
   * @param aOldVersion (in) A string indicating which version the user's
   *        profile is currently at, in format "X.Y.Z".
   * @return TRUE if any migration is necessary; else FALSE.
   */
  boolean needsMigration(in string aOldVersion);

  /**
   * Called to retrieve an object that will be passed to doMigrationWork() and
   * finishMigration() as the aMigrationContext argument.
   *
   * @param aOldVersion (in) A string indicating which version the user's
   *        profile is currently at, in format "X.Y.Z".
   * @param aProgressListener (in) A flockIMigrationProgressListener that
   *        should be used to report the migration's progress as a percentage.
   *
   *        In the degenerate case, startMigration() should report 0% and
   *        finishMigration() should report 100%. More sophisticated usage
   *        would have doMigrationWork() report increasing percentages as
   *        the migration progresses.
   * @return The context object.
   *
   * @see flockIMigrationProgressListener
   */
  nsISupports startMigration(in string aOldVersion,
                             in flockIMigrationProgressListener aProgressListener);

  /**
   * Called repeatedly to perform the migration, until it returns FALSE.
   *
   * @param aMigrationContext (in) The object returned from startMigration().
   * @return TRUE if more migration works needs to be done; else FALSE.
   */
  boolean doMigrationWork(in nsISupports aMigrationContext);

  /**
   * Called to provide an opportunity to perform any end-of-migration actions.
   *
   * @param aMigrationContext (in) The object returned from startMigration().
   */
  void finishMigration(in nsISupports aMigrationContext);
};


%{C++

// 481E822D-937F-4E76-8AFC-F636061B7AC6
#define FLOCK_MIGRATIONMANAGER_CID \
{ 0x481E822D, 0x937F, 0x4E76, { 0x8A, 0xFC, 0xF6, 0x36, 0x06, 0x1B, 0x7A, 0xC6 } }

#define FLOCK_MIGRATIONMANAGER_CLASSNAME "Flock Migration Manager"
#define FLOCK_MIGRATIONMANAGER_CONTRACTID "@flock.com/migration-manager;1"


%}
