profile/public/nsIProfileChangeStatus.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   ccarlen@netscape.com
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either of the GNU General Public License Version 2 or later (the "GPL"),
  27  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 #include "nsISupports.idl"
  40
  41 %{C++
  42
  43    /**
  44     * nsIObserver topics for profile changing. Profile changing happens in phases
  45     * in the order given below. An observer may register separately for each phase
  46     * of the process depending on its needs. The subject passed to the observer's
  47     * Observe() method can be QI'd to an nsIProfileChangeStatus.
  48     *
  49     * "profile-approve-change"
  50     *   Called before a profile change is attempted. Typically,
  51     *   the application level observer will ask the user if
  52     *   he/she wants to stop all network activity, close all open
  53     *   windows, etc. If the user says NO, the observer should
  54     *   call the subject's vetoChange(). If any observer does
  55     *   this, the profile will not be changed.
  56     *
  57     * "profile-change-teardown"
  58     *   All async activity must be stopped in this phase. Typically,
  59     *   the application level observer will close all open windows.
  60     *   This is the last phase in which the subject's vetoChange()
  61     *   method may still be called.
  62     *   The next notification will be either
  63     *   profile-change-teardown-veto or profile-before-change.
  64     *
  65     * "profile-change-teardown-veto"
  66     *   This notification will only be sent, if the profile change
  67     *   was vetoed during the profile-change-teardown phase.
  68     *   This allows components to bring back required resources,
  69     *   that were tore down on profile-change-teardown.
  70     *
  71     * "profile-before-change"
  72     *   Called before the profile has changed. Use this notification
  73     *   to prepare for the profile going away. If a component is
  74     *   holding any state which needs to be flushed to a profile-relative
  75     *   location, it should be done here.
  76     *
  77     * "profile-do-change"
  78     *   Called after the profile has changed. Do the work to
  79     *   respond to having a new profile. Any change which
  80     *   affects others must be done in this phase.
  81     *
  82     * "profile-after-change"
  83     *   Called after the profile has changed. Use this notification
  84     *   to make changes that are dependent on what some other listener
  85     *   did during its profile-do-change. For example, to respond to
  86     *   new preferences.
  87     *
  88     * "profile-initial-state"
  89     *   Called after all phases of a change have completed. Typically
  90     *   in this phase, an application level observer will open a new window.
  91     *
  92     * Contexts for profile changes. These are passed as the someData param to the
  93     * observer's Observe() method.
  94
  95     * "startup"
  96     *   Going from no profile to a profile.
  97     *
  98     *   The following topics happen in this context:
  99     *       profile-do-change
 100     *       profile-after-change
 101     *
 102     * "shutdown-persist"
 103     *   The user is logging out and whatever data the observer stores
 104     *   for the current profile should be released from memory and
 105     *   saved to disk.
 106     *
 107     * "shutdown-cleanse"
 108     *   The user is logging out and whatever data the observer stores
 109     *   for the current profile should be released from memory and
 110     *   deleted from disk.
 111     *
 112     *   The following topics happen in both shutdown contexts:
 113     *       profile-approve-change
 114     *       profile-change-teardown
 115     *       profile-before-change
 116     *
 117     * "switch"
 118     *   Going from one profile to another.
 119     *
 120     *   All of the above topics happen in a profile switch.
 121     *
 122     */
 123 %}
 124
 125
 126 [scriptable, uuid(2f977d43-5485-11d4-87e2-0010a4e75ef2)]
 127 interface nsIProfileChangeStatus : nsISupports {
 128
 129     void vetoChange();
 130
 131    /**
 132     * Called by a profile change observer when a fatal error
 133     * occurred during the attempt to switch the profile.
 134     *
 135     * The profile should be considered in an unsafe condition,
 136     * and the profile manager should inform the user and
 137     * exit immediately.
 138     *
 139     */
 140     void changeFailed();
 141
 142 };