chrome/browser/about_flags.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 #ifndef CHROME_BROWSER_ABOUT_FLAGS_H_
   6 #define CHROME_BROWSER_ABOUT_FLAGS_H_
   7
   8 #include <map>
   9 #include <string>
  10
  11 #include "base/command_line.h"
  12 #include "base/strings/string16.h"
  13
  14 class PrefService;
  15
  16 namespace base {
  17 class ListValue;
  18 }
  19
  20 namespace about_flags {
  21
  22 class FlagsStorage;
  23
  24 // Enumeration of OSs.
  25 // This is exposed only for testing.
  26 enum { kOsMac = 1 << 0, kOsWin = 1 << 1, kOsLinux = 1 << 2 , kOsCrOS = 1 << 3,
  27        kOsAndroid = 1 << 4, kOsCrOSOwnerOnly = 1 << 5 };
  28
  29 // Experiment is used internally by about_flags to describe an experiment (and
  30 // for testing).
  31 // This is exposed only for testing.
  32 struct Experiment {
  33   enum Type {
  34     // An experiment with a single value. This is typically what you want.
  35     SINGLE_VALUE,
  36
  37     // The experiment has multiple values only one of which is ever enabled.
  38     // The first of the values should correspond to a deactivated state for this
  39     // lab (i.e. no command line option). For MULTI_VALUE experiments the
  40     // command_line of the Experiment is not used. If the experiment is enabled
  41     // the command line of the selected Choice is enabled.
  42     MULTI_VALUE,
  43
  44     // The experiment has three possible values: Default, Enabled and Disabled.
  45     // This should be used for experiments that may have their own logic to
  46     // decide if the feature should be on when not explicitly specified via
  47     // about flags - for example via FieldTrials.
  48     ENABLE_DISABLE_VALUE,
  49   };
  50
  51   // Used for MULTI_VALUE types to describe one of the possible values the user
  52   // can select.
  53   struct Choice {
  54     // ID of the message containing the choice name.
  55     int description_id;
  56
  57     // Command line switch and value to enabled for this choice.
  58     const char* command_line_switch;
  59     // Simple switches that have no value should use "" for command_line_value.
  60     const char* command_line_value;
  61   };
  62
  63   // The internal name of the experiment. This is never shown to the user.
  64   // It _is_ however stored in the prefs file, so you shouldn't change the
  65   // name of existing flags.
  66   const char* internal_name;
  67
  68   // String id of the message containing the experiment's name.
  69   int visible_name_id;
  70
  71   // String id of the message containing the experiment's description.
  72   int visible_description_id;
  73
  74   // The platforms the experiment is available on
  75   // Needs to be more than a compile-time #ifdef because of profile sync.
  76   unsigned supported_platforms;  // bitmask
  77
  78   // Type of experiment.
  79   Type type;
  80
  81   // The commandline switch and value that are added when this flag is active.
  82   // This is different from |internal_name| so that the commandline flag can be
  83   // renamed without breaking the prefs file.
  84   // This is used if type is SINGLE_VALUE or ENABLE_DISABLE_VALUE.
  85   const char* command_line_switch;
  86   // Simple switches that have no value should use "" for command_line_value.
  87   const char* command_line_value;
  88
  89   // For ENABLE_DISABLE_VALUE, the command line switch and value to explictly
  90   // disable the feature.
  91   const char* disable_command_line_switch;
  92   const char* disable_command_line_value;
  93
  94   // This is used if type is MULTI_VALUE.
  95   const Choice* choices;
  96
  97   // Number of |choices|.
  98   // This is used if type is MULTI_VALUE.
  99   int num_choices;
 100
 101   // Returns the name used in prefs for the choice at the specified |index|.
 102   std::string NameForChoice(int index) const;
 103
 104   // Returns the human readable description for the choice at |index|.
 105   base::string16 DescriptionForChoice(int index) const;
 106 };
 107
 108 // A flag controlling the behavior of the |ConvertFlagsToSwitches| function -
 109 // whether it should add the sentinel switches around flags.
 110 enum SentinelsMode { kNoSentinels, kAddSentinels };
 111
 112 // Reads the Labs |prefs| (called "Labs" for historical reasons) and adds the
 113 // commandline flags belonging to the active experiments to |command_line|.
 114 void ConvertFlagsToSwitches(FlagsStorage* flags_storage,
 115                             base::CommandLine* command_line,
 116                             SentinelsMode sentinels);
 117
 118 // Compares a set of switches of the two provided command line objects and
 119 // returns true if they are the same and false otherwise.
 120 bool AreSwitchesIdenticalToCurrentCommandLine(
 121     const base::CommandLine& new_cmdline,
 122     const base::CommandLine& active_cmdline);
 123
 124 // Differentiate between generic flags available on a per session base and flags
 125 // that influence the whole machine and can be said by the admin only. This flag
 126 // is relevant for ChromeOS for now only and dictates whether entries marked
 127 // with the |kOsCrOSOwnerOnly| label should be enabled in the UI or not.
 128 enum FlagAccess { kGeneralAccessFlagsOnly, kOwnerAccessToFlags };
 129
 130 // Get the list of experiments. Experiments that are available on the current
 131 // platform are appended to |supported_experiments|; all other experiments are
 132 // appended to |unsupported_experiments|.
 133 void GetFlagsExperimentsData(FlagsStorage* flags_storage,
 134                              FlagAccess access,
 135                              base::ListValue* supported_experiments,
 136                              base::ListValue* unsupported_experiments);
 137
 138 // Returns true if one of the experiment flags has been flipped since startup.
 139 bool IsRestartNeededToCommitChanges();
 140
 141 // Enables or disables the experiment with id |internal_name|.
 142 void SetExperimentEnabled(FlagsStorage* flags_storage,
 143                           const std::string& internal_name,
 144                           bool enable);
 145
 146 // Removes all switches that were added to a command line by a previous call to
 147 // |ConvertFlagsToSwitches()|.
 148 void RemoveFlagsSwitches(
 149     std::map<std::string, base::CommandLine::StringType>* switch_list);
 150
 151 // Reset all flags to the default state by clearing all flags.
 152 void ResetAllFlags(FlagsStorage* flags_storage);
 153
 154 // Returns the value for the current platform. This is one of the values defined
 155 // by the OS enum above.
 156 // This is exposed only for testing.
 157 int GetCurrentPlatform();
 158
 159 // Sends UMA stats about experimental flag usage. This should be called once per
 160 // startup.
 161 void RecordUMAStatistics(FlagsStorage* flags_storage);
 162
 163 namespace testing {
 164
 165 // Clears internal global state, for unit tests.
 166 void ClearState();
 167
 168 // Sets the list of experiments. Pass in NULL to use the default set. This does
 169 // NOT take ownership of the supplied Experiments.
 170 void SetExperiments(const Experiment* e, size_t count);
 171
 172 // Returns the current set of experiments.
 173 const Experiment* GetExperiments(size_t* count);
 174
 175 // Separator used for multi values. Multi values are represented in prefs as
 176 // name-of-experiment + kMultiSeparator + selected_index.
 177 extern const char kMultiSeparator[];
 178
 179 }  // namespace testing
 180
 181 }  // namespace about_flags
 182
 183 #endif  // CHROME_BROWSER_ABOUT_FLAGS_H_