chrome/installer/util/master_preferences.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4 //
   5 // This file contains functions processing master preference file used by
   6 // setup and first run.
   7
   8 #ifndef CHROME_INSTALLER_UTIL_MASTER_PREFERENCES_H_
   9 #define CHROME_INSTALLER_UTIL_MASTER_PREFERENCES_H_
  10
  11 #include <string>
  12 #include <vector>
  13
  14 #include "base/command_line.h"
  15 #include "base/memory/scoped_ptr.h"
  16
  17 namespace base {
  18 class DictionaryValue;
  19 class FilePath;
  20 }
  21
  22 namespace installer {
  23
  24 #if !defined(OS_MACOSX)
  25 // This is the default name for the master preferences file used to pre-set
  26 // values in the user profile at first run.
  27 const char kDefaultMasterPrefs[] = "master_preferences";
  28 #endif
  29
  30 // The master preferences is a JSON file with the same entries as the
  31 // 'Default\Preferences' file. This function parses the distribution
  32 // section of the preferences file.
  33 //
  34 // A prototypical 'master_preferences' file looks like this:
  35 //
  36 // {
  37 //   "distribution": {
  38 //      "alternate_shortcut_text": false,
  39 //      "auto_launch_chrome": false,
  40 //      "chrome_shortcut_icon_index": 0,
  41 //      "create_all_shortcuts": true,
  42 //      "import_bookmarks": false,
  43 //      "import_bookmarks_from_file": "c:\\path",
  44 //      "import_history": false,
  45 //      "import_home_page": false,
  46 //      "import_search_engine": true,
  47 //      "ping_delay": 40,
  48 //      "show_welcome_page": true,
  49 //      "skip_first_run_ui": true,
  50 //      "do_not_launch_chrome": false,
  51 //      "make_chrome_default": false,
  52 //      "make_chrome_default_for_user": true,
  53 //      "require_eula": true,
  54 //      "system_level": false,
  55 //      "verbose_logging": true,
  56 //      "welcome_page_on_os_upgrade_enabled": false
  57 //   },
  58 //   "browser": {
  59 //      "show_home_button": true
  60 //   },
  61 //   "bookmark_bar": {
  62 //      "show_on_all_tabs": true
  63 //   },
  64 //   "first_run_tabs": [
  65 //      "http://gmail.com",
  66 //      "https://igoogle.com"
  67 //   ],
  68 //   "homepage": "http://example.org",
  69 //   "homepage_is_newtabpage": false
  70 // }
  71 //
  72 // A reserved "distribution" entry in the file is used to group related
  73 // installation properties. This entry will be ignored at other times.
  74 // This function parses the 'distribution' entry and returns a combination
  75 // of MasterPrefResult.
  76
  77 class MasterPreferences {
  78  public:
  79   // Construct a master preferences from the current process' current command
  80   // line. Equivalent to calling
  81   // MasterPreferences(*CommandLine::ForCurrentProcess()).
  82   MasterPreferences();
  83
  84   // Parses the command line and optionally reads the master preferences file
  85   // to get distribution related install options (if the "installerdata" switch
  86   // is present in the command line.
  87   // The options from the preference file and command line are merged, with the
  88   // ones from the command line taking precedence in case of a conflict.
  89   explicit MasterPreferences(const base::CommandLine& cmd_line);
  90
  91   // Parses a specific preferences file and does not merge any command line
  92   // switches with the distribution dictionary.
  93   explicit MasterPreferences(const base::FilePath& prefs_path);
  94
  95   // Parses a preferences directly from |prefs| and does not merge any command
  96   // line switches with the distribution dictionary.
  97   explicit MasterPreferences(const std::string& prefs);
  98
  99   ~MasterPreferences();
 100
 101   // Each of the Get methods below returns true if the named value was found in
 102   // the distribution dictionary and its value assigned to the 'value'
 103   // parameter.  If the value wasn't found, the return value is false.
 104   bool GetBool(const std::string& name, bool* value) const;
 105   bool GetInt(const std::string& name, int* value) const;
 106   bool GetString(const std::string& name, std::string* value) const;
 107
 108   // As part of the master preferences an optional section indicates the tabs
 109   // to open during first run. An example is the following:
 110   //
 111   //  {
 112   //    "first_run_tabs": [
 113   //       "http://google.com/f1",
 114   //       "https://google.com/f2"
 115   //    ]
 116   //  }
 117   //
 118   // Note that the entries are usually urls but they don't have to be.
 119   //
 120   // An empty vector is returned if the first_run_tabs preference is absent.
 121   std::vector<std::string> GetFirstRunTabs() const;
 122
 123   // The master preferences can also contain a regular extensions
 124   // preference block. If so, the extensions referenced there will be
 125   // installed during the first run experience.
 126   // An extension can go in the master prefs needs just the basic
 127   // elements such as:
 128   //   1- An extension entry under settings, assigned by the gallery
 129   //   2- The "location" : 1 entry
 130   //   3- A minimal "manifest" block with key, name, permissions, update url
 131   //      and version. The version needs to be lower than the version of
 132   //      the extension that is hosted in the gallery.
 133   //   4- The "path" entry with the version as last component
 134   //   5- The "state" : 1 entry
 135   //
 136   // The following is an example of a master pref file that installs
 137   // Google XYZ:
 138   //
 139   //  {
 140   //     "extensions": {
 141   //        "settings": {
 142   //           "ppflmjolhbonpkbkooiamcnenbmbjcbb": {
 143   //              "location": 1,
 144   //              "manifest": {
 145   //                 "key": "MIGfMA0GCSqGSIb3DQEBAQUAA4<rest of key ommited>",
 146   //                 "name": "Google XYZ (Installing...)",
 147   //                 "permissions": [ "tabs", "http://xyz.google.com/" ],
 148   //                 "update_url": "http://fixme.com/fixme/fixme/crx",
 149   //                 "version": "0.0"
 150   //              },
 151   //              "path": "ppflmjolhbonpkbkooiamcnenbmbjcbb\\0.0",
 152   //              "state": 1
 153   //           }
 154   //        }
 155   //     }
 156   //  }
 157   //
 158   bool GetExtensionsBlock(base::DictionaryValue** extensions) const;
 159
 160   // Returns the compressed variations seed entry from the master prefs.
 161   std::string GetCompressedVariationsSeed() const;
 162
 163   // Returns the variations seed entry from the master prefs.
 164   std::string GetVariationsSeed() const;
 165
 166   // Returns the variations seed signature entry from the master prefs.
 167   std::string GetVariationsSeedSignature() const;
 168
 169   // Returns true iff the master preferences were successfully read from a file.
 170   bool read_from_file() const {
 171     return preferences_read_from_file_;
 172   }
 173
 174   bool install_chrome() const {
 175     return chrome_;
 176   }
 177
 178   bool is_multi_install() const {
 179     return multi_install_;
 180   }
 181
 182   // Returns a reference to this MasterPreferences' root dictionary of values.
 183   const base::DictionaryValue& master_dictionary() const {
 184     return *master_dictionary_.get();
 185   }
 186
 187   // Returns a static preference object that has been initialized with the
 188   // CommandLine object for the current process.
 189   // NOTE: Must not be called before CommandLine::Init() is called!
 190   // OTHER NOTE: Not thread safe.
 191   static const MasterPreferences& ForCurrentProcess();
 192
 193  private:
 194   void InitializeFromCommandLine(const base::CommandLine& cmd_line);
 195   void InitializeFromFilePath(const base::FilePath& prefs_path);
 196
 197   // Initializes the instance from a given JSON string, returning true if the
 198   // string was successfully parsed.
 199   bool InitializeFromString(const std::string& json_data);
 200
 201   void InitializeProductFlags();
 202
 203   // Enforces legacy preferences that should no longer be used, but could be
 204   // found in older master_preferences files.
 205   void EnforceLegacyPreferences();
 206
 207   // Removes the specified string pref from the master preferences and returns
 208   // its value. Should be used for master prefs that shouldn't be automatically
 209   // copied over to profile preferences.
 210   std::string ExtractPrefString(const std::string& name) const;
 211
 212   scoped_ptr<base::DictionaryValue> master_dictionary_;
 213   base::DictionaryValue* distribution_;
 214   bool preferences_read_from_file_;
 215   bool chrome_;
 216   bool multi_install_;
 217
 218  private:
 219   DISALLOW_COPY_AND_ASSIGN(MasterPreferences);
 220 };
 221
 222 }  // namespace installer
 223
 224 #endif  // CHROME_INSTALLER_UTIL_MASTER_PREFERENCES_H_