path: root/comm/mail/components/activity/nsIActivity.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "nsISupportsPrimitives.idl"

interface nsIActivityListener;
interface nsIActivity;
interface nsIActivityProcess;
interface nsIActivityEvent;
interface nsIActivityWarning;
interface nsIVariant;
interface nsISupportsPRTime;

/**
 * See https://wiki.mozilla.org/Thunderbird:Activity_Manager/Developer for UML
 * diagram and sample codes.
 */

/**
 * Background:
 * Activity handlers define the behavioral capabilities of the activities. They
 * are used by the Activity Manager to change the execution flow of the activity
 * based on the user interaction. They are not mandatory, but when set, causes
 * behavioral changes on the binding representing the activity, such as showing
 * a cancel button, etc. The following handlers are currently supported;
 */

/**
 * The handler to invoke when the recover button is pressed. Used by a Warning
 * to recover from the situation causing the warning. For instance, recovery
 * action for a "Over Quota Limit" warning, would be to cleanup some disk space,
 * and this operation can be implemented and set by the activity developer in
 * form of nsIActivityRecoveryHandler component.
 */
[scriptable, uuid(30E0A76F-880A-4093-8F3C-AF2239977A3D)]
interface nsIActivityRecoveryHandler : nsISupports {
  nsresult recover(in nsIActivityWarning aActivity);
};

/**
 * The handler to invoke when the cancel button is pressed. Used by a Process to
 * cancel the operation.
 */
[scriptable, uuid(35ee2461-70db-4b3a-90d0-7a68c856e911)]
interface nsIActivityCancelHandler : nsISupports {
  nsresult cancel(in nsIActivityProcess aActivity);
};

/**
 * The handler to invoke when the pause button is pressed. Used by a Process to
 * pause/resume the operation.
 */
[scriptable, uuid(9eee22bf-5378-460e-83a7-781cdcc9050b)]
interface nsIActivityPauseHandler : nsISupports {
  nsresult pause(in nsIActivityProcess aActivity);
  nsresult resume(in nsIActivityProcess aActivity);
};

/**
 * The handler to invoke when the retry button is pressed. Used by a Process to
 * retry the operation in case of failure.
 */
[scriptable, uuid(8ec42517-951f-4bc0-aba5-fde7258b1705)]
interface nsIActivityRetryHandler : nsISupports {
  nsresult retry(in nsIActivityProcess aActivity);
};

/**
 * The handler to invoke when the undo button is pressed. Used by a Event to
 * undo the operation generated the event.
 */
[scriptable, uuid(b8632ac7-9d8b-4341-a349-ef000e8c89ac)]
interface nsIActivityUndoHandler : nsISupports {
  nsresult undo(in nsIActivityEvent aActivity);
};

/**
 * Base interface of all activity interfaces. It is abstract in a sense that
 * there is no component in the activity management system that solely
 * implements this interface.
 */
[scriptable, uuid(6CD33E65-B2D8-4634-9B6D-B80BF1273E99)]
interface nsIActivity : nsISupports {

  /**
   * Shows the activity as a standalone item.
   */
  const short GROUPING_STYLE_STANDALONE = 1;

  /**
   * Groups activity by its context.
   */
  const short GROUPING_STYLE_BYCONTEXT = 2;

  /**
   * Internal ID given by the activity manager when
   * added into the activity list.  Not readonly so that
   * the activity manager can write to them, but not to be written to
   * by anyone else.
   */
  attribute unsigned long id;

  // Following attributes change the UI characteristics of the activity

  /**
   * A brief description of the activity, to be shown by the
   * associated binding (XBL) in the Activity Manager window.
   */
  readonly attribute AString displayText;

  /**
   * Changes the default icon associated with the activity. Core activity
   * icons are declared in |mail/themes/<themename>/mail/activity/activity.css|
   * files.
   *
   * Extension developers can add and assign their own icons by setting
   * this attribute.
   */
  attribute AString iconClass;

  /**
   * Textual id of the XBL binding that will be used to represent the
   * activity in the Activity Manager window.
   *
   * This attribute allows to associate default activity components
   * with custom XBL bindings. See |activity.xml| file for default
   * activity XBL bindings, and |activity.css| file for default binding
   * associations.
   */
  attribute AString bindingName;

  /**
   * Defines the grouping style of the activity when being shown in the
   * activity manager window:
   *  GROUPING_STYLE_STANDALONE or GROUPING_STYLE_BYCONTEXT
   */
  attribute short groupingStyle;

  /**
   * A text value to associate a facet type with the activity. If empty,
   * the activity will be shown in the 'Misc' section.
   */
  attribute AString facet;

  // UI related attributes end.

  /**
   * Gets the initiator of the activity. An initiator represents an object
   * that generates and controls the activity. For example, Copy Service can be
   * the initiator of the copy, and move activities. Similarly Gloda can be the
   * initiator of indexing activity, etc.
   *
   * This attribute is used mostly by handler components to change the execution
   * flow of the activity such as canceling, pausing etc. Since not used by the
   * Activity Manager, it is not mandatory to set it.
   *
   * An initiator can be any JS Object or an XPCOM component that provides an
   * nsIVariant interface.
   */
  readonly attribute nsIVariant initiator;

  /**
   * Adds an object to the activity's internal subject list. Subject list
   * provides argument(s) to activity handlers to complete their operation.
   * For example, nsIActivityUndoHandler needs the source and destination
   * folders to undo a move operation.
   *
   * Since subjects are not used by the Activity Manager, it is up to the
   * activity developer to provide these objects.
   *
   * A subject can be any JS object or XPCOM component that supports nsIVariant
   * interface.
   */
  void addSubject(in nsIVariant aSubject);

  /**
   * Retrieves all subjects associated with this activity.
   *
   * @return The list of subject objects associated by the activity.
   */
  Array<nsIVariant> getSubjects();

  /*
   * Background:
   *  A context is a generic concept that is used to group the processes and
   *  warnings having similar properties such as same imap server, same smtp
   *  server etc.
   *  A context is uniquely identified by its "type" and "object" attributes.
   *  Each activity that has the same context type and object are considered
   *  belong to the same logical group, context.
   *
   *  There are 4 predefined context types known by the Activity Manager:
   *  Account, Smtp, Calendar, and Addressbook. The most common context type
   *  for activities is the "Account Context" and when combined with an account
   *  server instance, it allows to group different activities happening on the
   *  the same account server.
   */

  /**
   * Sets and gets the context object of the activity. A context object can be
   * any JS object or XPCOM component that supports nsIVariant interface.
   */
  attribute nsIVariant contextObj;

  /**
   * Sets and gets the context type of the activity. If this is set, then
   * the contextDisplayText should also be set.
   */
  attribute AString contextType;

  /**
   * Return the displayText to be used for the context
   **/
  attribute AString contextDisplayText;

  /**
   * Adds a listener. See nsIActivityListener below.
   */
  void addListener(in nsIActivityListener aListener);

  /**
   * Removes the given listener. See nsIActivityListener below.
   */
  void removeListener(in nsIActivityListener aListener);
};


/**
 * A Process represents an on-going activity.
 */
[scriptable, uuid(9DC7CA67-828D-4AFD-A5C6-3ECE091A98B8)]
interface nsIActivityProcess : nsIActivity {

  /**
   * Default state for uninitialized process activity
   * object.
   */
  const short STATE_NOTSTARTED = -1;

  /**
   * Activity is currently in progress.
   */
  const short STATE_INPROGRESS = 0;

  /**
   * Activity is completed.
   */
  const short STATE_COMPLETED = 1;

  /**
   * Activity was canceled by the user.
   * (same as completed)
   */
  const short STATE_CANCELED = 2;

  /**
   * Activity was paused by the user.
   */
  const short STATE_PAUSED = 3;

  /**
   * Activity waits for the user input's to retry.
   * (i.e. login password)
   */
  const short STATE_WAITINGFORINPUT = 4;

  /**
   * Activity is ready for an automatic or manual retry.
   */
  const short STATE_WAITINGFORRETRY = 5;

  /**
   * The state of the activity.
   * See above for possible values.
   * @exception NS_ERROR_ILLEGAL_VALUE if the state isn't one of the states
   *   defined above.
   */
  attribute short state;

  /**
   * The percentage of activity completed.
   * If the max value is unknown it'll be -1 here.
   */
  readonly attribute long percentComplete;

  /**
   * A brief text about the process' status.
   */
  readonly attribute AString lastStatusText;

  /**
   * The amount of work units completed so far.
   */
  readonly attribute unsigned long workUnitComplete;

  /**
   * Total amount of work units.
   */
  readonly attribute unsigned long totalWorkUnits;

  /**
   * The starting time of the process.
   * 64-bit signed integers relative to midnight (00:00:00), January 1, 1970
   * Greenwich Mean Time (GMT). (GMT is also known as Coordinated Universal
   * Time, UTC.). The units of time are in microseconds.
   *
   * In JS Date.now(), in C++ PR_Now() / PR_USEC_PER_MSEC can be used to set
   * this value.
   */
  readonly attribute long long startTime;

  /**
   * The handler to invoke when the cancel button is pressed. If present
   * (non-null), the activity can be canceled and a cancel button will be
   * displayed to the user.  If null, it cannot be canceled and no button will
   * be displayed.
   */
  attribute nsIActivityCancelHandler cancelHandler;

  /**
   * The handler to invoke when the pause button is pressed. If present
   * (non-null), the activity can be pauseable and a pause button will be
   * displayed to the user.  If null, it cannot be paused and no button will
   * be displayed.
   */
  attribute nsIActivityPauseHandler pauseHandler;

  /**
   * The handler to invoke when the retry button is pressed. If present
   * (non-null), the activity can be retryable and a retry button will be
   * displayed to the user.  If null, it cannot be retried and no button will
   * be displayed.
   */
  attribute nsIActivityRetryHandler retryHandler;

  /**
   * Updates the activity progress info.
   *
   * @param aStatusText A localized text describing the current status of the
   *                    process
   * @param aWorkUnitComplete The amount of work units completed. Not used by
   *                          Activity Manager or default binding for any
   *                          purpose.
   * @param aTotalWorkUnits Total amount of work units. Not used by
   *                        Activity Manager or default binding for any
   *                        purpose. If set to zero, this indicates that the
   *                        number of work units is unknown, and the percentage
   *                        attribute will be set to -1.
   */
  void setProgress(in AString aStatusText,
                   in unsigned long aWorkUnitComplete,
                   in unsigned long aTotalWorkUnits);

  /**
   * Component initialization method.
   *
   * @param aDisplayText A localized text to be shown on the Activity Manager
   *                     window
   * @param aInitiator The initiator of the process
   */
  void init(in AString aDisplayText, in nsIVariant aInitiator);
};

/**
 * Historical actions performed by the user, by extensions or by the system.
 */
[scriptable, uuid(5B1B0D03-2820-4E37-8BF8-102AFDE4FC45)]
interface nsIActivityEvent : nsIActivity {

  /**
   * Any localized textual information related to this event.
   * It is shown at the bottom of the displayText area.
   */
  readonly attribute AString statusText;

  /**
   * The starting time of the event.
   * 64-bit signed integers relative to midnight (00:00:00), January 1, 1970
   * Greenwich Mean Time (GMT). (GMT is also known as Coordinated Universal
   * Time, UTC.). The units of time are in microseconds.
   *
   * In JS Date.now(), in C++ PR_Now() / PR_USEC_PER_MSEC can be used to set
   * this value.
   */
  readonly attribute long long startTime;

  /**
   * The completion time of the event in microseconds.
   * 64-bit signed integers relative to midnight (00:00:00), January 1, 1970
   * Greenwich Mean Time (GMT). (GMT is also known as Coordinated Universal
   * Time, UTC.). The units of time are in microseconds.
   *
   * In JS Date.now(), in C++ PR_Now() / PR_USEC_PER_MSEC can be used to set
   * this value.
   */
  readonly attribute long long completionTime;

  /**
   * The handler to invoke when the undo button is pressed.  If present
   * (non-null), the activity can be undoable and an undo button will be
   * displayed to the user.  If null, it cannot be undone and no button will
   * be displayed.
   */
  attribute nsIActivityUndoHandler undoHandler;

  /**
   * Component initialization method.
   *
   * @param aDisplayText Any localized text describing the event and its context
   * @param aInitiator The initiator of the event
   * @param aStatusText Any localized additional information about the event
   * @param aStartTime The starting time of the event
   * @param aCompletionTime The completion time of the event
   */
  void init(in AString aDisplayText, in nsIVariant aInitiator,
            in AString aStatusText, in long long aStartTime,
            in long long aCompletionTime);
};

[scriptable, uuid(8265833e-c604-4585-a43c-a76bd8ed3a8c)]
interface nsIActivityWarning : nsIActivity {

  /**
   * Any localized textual information related to this warning.
   */
  readonly attribute AString warningText;

  /**
   * The time of the warning.
   * 64-bit signed integers relative to midnight (00:00:00), January 1, 1970
   * Greenwich Mean Time (GMT). (GMT is also known as Coordinated Universal
   * Time, UTC.). The units of time are in microseconds.
   *
   * In JS Date.now(), in C++ PR_Now() / PR_USEC_PER_MSEC can be used to set
   * this value.
   */
  readonly attribute long long time;

  /**
   * Recovery tip of the warning, localized.
   */
  readonly attribute AString recoveryTipText;

  /**
   * The handler to invoke when the recover button is pressed.  If present
   * (non-null), the activity can be recoverable and a recover button will be
   * displayed to the user.  If null, it cannot be recovered and no button will
   * be displayed.
   */
  attribute nsIActivityRecoveryHandler recoveryHandler;

  /**
   * Component initialization method.
   *
   * @param aWarningText The localized text that will be shown on the display
   *                     area
   * @param aInitiator The initiator of the warning
   * @param aRecoveryTip A localized textual information to guide the user in
   *                     order to recover from the warning situation.
   */
  void init(in AString aWarningText, in nsIVariant aInitiator,
            in AString aRecoveryTip);
};

[scriptable, uuid(bd11519f-b297-4b34-a793-1861dc90d5e9)]
interface nsIActivityListener : nsISupports {
  /**
   * Triggered after activity state is changed.
   */
  void onStateChanged(in nsIActivity aActivity, in short aOldState);

  /**
   * Triggered after the progress of the process activity is changed.
   */
  void onProgressChanged(in nsIActivity aActivity,
                         in AString aStatusText,
                         in unsigned long aWorkUnitsCompleted,
                         in unsigned long aTotalWorkUnits);

  /**
   * Triggered after one of the activity handler is set.
   *
   * This is mostly used to update the UI of the activity when
   * one of the handler is set to null after the operation is completed.
   * For example after the activity is undone, to make the undo button
   * invisible.
   */
  void onHandlerChanged(in nsIActivity aActivity);
};