toolkit/profile/nsIToolkitProfileService.idl

   1 /* -*- Mode: IDL; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsISimpleEnumerator;
   9 interface nsIFile;
  10 interface nsIToolkitProfile;
  11 interface nsIProfileLock;
  12
  13 [scriptable, builtinclass, uuid(1947899b-f369-48fa-89da-f7c37bb1e6bc)]
  14 interface nsIToolkitProfileService : nsISupports
  15 {
  16     /**
  17      * Tests whether the profile lists on disk have changed since they were
  18      * loaded. When this is true attempts to flush changes to disk will fail.
  19      */
  20     [infallible] readonly attribute boolean isListOutdated;
  21
  22     /**
  23      * When a downgrade is detected UI is presented to the user to ask how to
  24      * proceed. These flags are used to pass some information to the UI.
  25      */
  26     cenum downgradeUIFlags: 8 {
  27         hasSync = 1,
  28     };
  29
  30     /**
  31      * When a downgrade is detected UI is presented to the user to ask how to
  32      * proceed. These are the possible options the user can choose.
  33      */
  34     cenum downgradeUIChoice: 8 {
  35         quit = 0,
  36         createNewProfile = 1,
  37     };
  38
  39     cenum profileManagerResult: 8 {
  40         exit = 0,
  41         launchWithProfile = 1,
  42         restart = 2,
  43     };
  44
  45     attribute boolean startWithLastProfile;
  46
  47     readonly attribute nsISimpleEnumerator /*nsIToolkitProfile*/ profiles;
  48
  49     /**
  50      * The profile currently in use if it is a named profile. This will return
  51      * null if the current profile path doesn't match a profile in the database.
  52      */
  53     readonly attribute nsIToolkitProfile currentProfile;
  54
  55     /**
  56      * The default profile for this build.
  57      * On startup this is the profile selected unless overridden by command line
  58      * arguments or environment variables. Setting this will change the profile
  59      * used by default the next time the application is started.
  60      * Attempting to change the default may throw an exception on builds that do
  61      * not support changing the default profile, such as developer edition.
  62      */
  63     attribute nsIToolkitProfile defaultProfile;
  64
  65     /**
  66      * Selects or creates a profile to use based on the profiles database, any
  67      * environment variables and any command line arguments. Will not create
  68      * a profile if aIsResetting is true. The profile is selected based on this
  69      * order of preference:
  70      * * Environment variables (set when restarting the application).
  71      * * --profile command line argument.
  72      * * --createprofile command line argument (this also causes the app to exit).
  73      * * -p command line argument.
  74      * * A new profile created if this is the first run of the application.
  75      * * The default profile.
  76      * aRootDir and aLocalDir are set to the data and local directories for the
  77      * profile data. If a profile from the database was selected it will be
  78      * returned in aProfile.
  79      * This returns true if a new profile was created.
  80      * This method is primarily for testing. It can be called only once.
  81      */
  82     bool selectStartupProfile(in Array<ACString> aArgv,
  83                               in boolean aIsResetting, in AUTF8String aUpdateChannel,
  84                               in AUTF8String aLegacyInstallHash,
  85                               out nsIFile aRootDir, out nsIFile aLocalDir,
  86                               out nsIToolkitProfile aProfile);
  87
  88     /**
  89      * Get a profile by name. This is mainly for use by the -P
  90      * commandline flag.
  91      *
  92      * @param aName The profile name to find.
  93      */
  94     nsIToolkitProfile getProfileByName(in AUTF8String aName);
  95
  96     /**
  97      * Create a new profile.
  98      *
  99      * The profile temporary directory will be chosen based on where the
 100      * profile directory is located.
 101      *
 102      * If a profile with the given name already exists it will be returned
 103      * instead of creating a new profile.
 104      *
 105      * @param aRootDir
 106      *        The profile directory. May be null, in which case a suitable
 107      *        default will be chosen based on the profile name.
 108      * @param aName
 109      *        The profile name.
 110      */
 111     nsIToolkitProfile createProfile(in nsIFile aRootDir,
 112                                     in AUTF8String aName);
 113
 114     /**
 115      * Create a new profile with a unique name.
 116      *
 117      * As above however the name given will be altered to make it a unique
 118      * profile name.
 119      *
 120      * @param aRootDir
 121      *        The profile directory. May be null, in which case a suitable
 122      *        default will be chosen based on the profile name.
 123      * @param aNamePrefix
 124      *        The prefix to use for the profile name. If unused this will be
 125      *        used as the profile name otherwise additional characters will be
 126      *        added to make the name unique.
 127      */
 128     nsIToolkitProfile createUniqueProfile(in nsIFile aRootDir,
 129                                           in AUTF8String aNamePrefix);
 130
 131     /**
 132      * Returns the number of profiles.
 133      * @return the number of profiles.
 134      */
 135     readonly attribute unsigned long profileCount;
 136
 137     /**
 138      * Flush the profiles list file. This will fail with
 139      * NS_ERROR_DATABASE_CHANGED if the files on disk have changed since the
 140      * profiles were loaded.
 141      */
 142     void flush();
 143 };
 144
 145 %{C++
 146 #define NS_PROFILESERVICE_CONTRACTID "@mozilla.org/toolkit/profile-service;1"
 147 %}