Revision control
Copy as Markdown
Other Tools
/* -*- 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
#include "nsISupports.idl"
#include "nsISupportsPrimitives.idl"
interface nsIActivityListener;
interface nsIActivity;
interface nsIActivityProcess;
interface nsIActivityEvent;
interface nsIActivityWarning;
interface nsIVariant;
interface nsISupportsPRTime;
/**
* 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);
};