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