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
  13 class PrefService;
  14
  15 namespace base {
  16 class ListValue;
  17 }
  18
  19 namespace about_flags {
  20
  21 // Enumeration of OSs.
  22 // This is exposed only for testing.
  23 enum { kOsMac = 1 << 0, kOsWin = 1 << 1, kOsLinux = 1 << 2 , kOsCrOS = 1 << 3,
  24        kOsAndroid = 1 << 4 };
  25
  26 // Experiment is used internally by about_flags to describe an experiment (and
  27 // for testing).
  28 // This is exposed only for testing.
  29 struct Experiment {
  30   enum Type {
  31     // An experiment with a single value. This is typically what you want.
  32     SINGLE_VALUE,
  33
  34     // The experiment has multiple values only one of which is ever enabled.
  35     // The first of the values should correspond to a deactivated state for this
  36     // lab (i.e. no command line option). For MULTI_VALUE experiments the
  37     // command_line of the Experiment is not used. If the experiment is enabled
  38     // the command line of the selected Choice is enabled.
  39     MULTI_VALUE,
  40   };
  41
  42   // Used for MULTI_VALUE types to describe one of the possible values the user
  43   // can select.
  44   struct Choice {
  45     // ID of the message containing the choice name.
  46     int description_id;
  47
  48     // Command line switch and value to enabled for this choice.
  49     const char* command_line_switch;
  50     // Simple switches that have no value should use "" for command_line_value.
  51     const char* command_line_value;
  52   };
  53
  54   // The internal name of the experiment. This is never shown to the user.
  55   // It _is_ however stored in the prefs file, so you shouldn't change the
  56   // name of existing flags.
  57   const char* internal_name;
  58
  59   // String id of the message containing the experiment's name.
  60   int visible_name_id;
  61
  62   // String id of the message containing the experiment's description.
  63   int visible_description_id;
  64
  65   // The platforms the experiment is available on
  66   // Needs to be more than a compile-time #ifdef because of profile sync.
  67   unsigned supported_platforms;  // bitmask
  68
  69   // Type of experiment.
  70   Type type;
  71
  72   // The commandline switch and value that are added when this lab is active.
  73   // This is different from |internal_name| so that the commandline flag can be
  74   // renamed without breaking the prefs file.
  75   // This is used if type is SINGLE_VALUE.
  76   const char* command_line_switch;
  77   // Simple switches that have no value should use "" for command_line_value.
  78   const char* command_line_value;
  79
  80   // This is used if type is MULTI_VALUE.
  81   const Choice* choices;
  82
  83   // Number of |choices|.
  84   // This is used if type is MULTI_VALUE.
  85   int num_choices;
  86 };
  87
  88 // Reads the Labs |prefs| (called "Labs" for historical reasons) and adds the
  89 // commandline flags belonging to the active experiments to |command_line|.
  90 void ConvertFlagsToSwitches(PrefService* prefs, CommandLine* command_line);
  91
  92 // Get a list of all available experiments. The caller owns the result.
  93 base::ListValue* GetFlagsExperimentsData(PrefService* prefs);
  94
  95 // Returns true if one of the experiment flags has been flipped since startup.
  96 bool IsRestartNeededToCommitChanges();
  97
  98 // Enables or disables the experiment with id |internal_name|.
  99 void SetExperimentEnabled(
 100     PrefService* prefs, const std::string& internal_name, bool enable);
 101
 102 // Removes all switches that were added to a command line by a previous call to
 103 // |ConvertFlagsToSwitches()|.
 104 void RemoveFlagsSwitches(
 105     std::map<std::string, CommandLine::StringType>* switch_list);
 106
 107 // Returns the value for the current platform. This is one of the values defined
 108 // by the OS enum above.
 109 // This is exposed only for testing.
 110 int GetCurrentPlatform();
 111
 112 // Sends UMA stats about experimental flag usage. This should be called once per
 113 // startup.
 114 void RecordUMAStatistics(const PrefService* prefs);
 115
 116 namespace testing {
 117 // Clears internal global state, for unit tests.
 118 void ClearState();
 119
 120 // Sets the list of experiments. Pass in NULL to use the default set. This does
 121 // NOT take ownership of the supplied Experiments.
 122 void SetExperiments(const Experiment* e, size_t count);
 123
 124 // Returns the current set of experiments.
 125 const Experiment* GetExperiments(size_t* count);
 126
 127 // Separator used for multi values. Multi values are represented in prefs as
 128 // name-of-experiment + kMultiSeparator + selected_index.
 129 extern const char kMultiSeparator[];
 130
 131 }  // namespace testing
 132
 133 }  // namespace about_flags
 134
 135 #endif  // CHROME_BROWSER_ABOUT_FLAGS_H_