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.
5 #ifndef CHROME_BROWSER_ABOUT_FLAGS_H_
6 #define CHROME_BROWSER_ABOUT_FLAGS_H_
11 #include "base/command_line.h"
12 #include "base/strings/string16.h"
20 namespace about_flags
{
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 };
29 // Experiment is used internally by about_flags to describe an experiment (and
31 // This is exposed only for testing.
34 // An experiment with a single value. This is typically what you want.
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.
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.
51 // Used for MULTI_VALUE types to describe one of the possible values the user
54 // ID of the message containing the choice name.
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
;
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
;
68 // String id of the message containing the experiment's name.
71 // String id of the message containing the experiment's description.
72 int visible_description_id
;
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
78 // Type of experiment.
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
;
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
;
94 // This is used if type is MULTI_VALUE.
95 const Choice
* choices
;
97 // Number of |choices|.
98 // This is used if type is MULTI_VALUE.
101 // Returns the name used in prefs for the choice at the specified |index|.
102 std::string
NameForChoice(int index
) const;
104 // Returns the human readable description for the choice at |index|.
105 string16
DescriptionForChoice(int index
) const;
108 // Reads the Labs |prefs| (called "Labs" for historical reasons) and adds the
109 // commandline flags belonging to the active experiments to |command_line|.
110 void ConvertFlagsToSwitches(FlagsStorage
* flags_storage
,
111 CommandLine
* command_line
);
113 // Compares a set of switches of the two provided command line objects and
114 // returns true if they are the same and false otherwise.
115 bool AreSwitchesIdenticalToCurrentCommandLine(
116 const CommandLine
& new_cmdline
, const CommandLine
& active_cmdline
);
118 // Differentiate between generic flags available on a per session base and flags
119 // that influence the whole machine and can be said by the admin only. This flag
120 // is relevant for ChromeOS for now only and dictates whether entries marked
121 // with the |kOsCrOSOwnerOnly| label should be enabled in the UI or not.
122 enum FlagAccess
{ kGeneralAccessFlagsOnly
, kOwnerAccessToFlags
};
124 // Get the list of experiments. Experiments that are available on the current
125 // platform are appended to |supported_experiments|; all other experiments are
126 // appended to |unsupported_experiments|.
127 void GetFlagsExperimentsData(FlagsStorage
* flags_storage
,
129 base::ListValue
* supported_experiments
,
130 base::ListValue
* unsupported_experiments
);
132 // Returns true if one of the experiment flags has been flipped since startup.
133 bool IsRestartNeededToCommitChanges();
135 // Enables or disables the experiment with id |internal_name|.
136 void SetExperimentEnabled(FlagsStorage
* flags_storage
,
137 const std::string
& internal_name
,
140 // Removes all switches that were added to a command line by a previous call to
141 // |ConvertFlagsToSwitches()|.
142 void RemoveFlagsSwitches(
143 std::map
<std::string
, CommandLine::StringType
>* switch_list
);
145 // Reset all flags to the default state by clearing all flags.
146 void ResetAllFlags(FlagsStorage
* flags_storage
);
148 // Returns the value for the current platform. This is one of the values defined
149 // by the OS enum above.
150 // This is exposed only for testing.
151 int GetCurrentPlatform();
153 // Sends UMA stats about experimental flag usage. This should be called once per
155 void RecordUMAStatistics(FlagsStorage
* flags_storage
);
159 // Clears internal global state, for unit tests.
162 // Sets the list of experiments. Pass in NULL to use the default set. This does
163 // NOT take ownership of the supplied Experiments.
164 void SetExperiments(const Experiment
* e
, size_t count
);
166 // Returns the current set of experiments.
167 const Experiment
* GetExperiments(size_t* count
);
169 // Separator used for multi values. Multi values are represented in prefs as
170 // name-of-experiment + kMultiSeparator + selected_index.
171 extern const char kMultiSeparator
[];
173 } // namespace testing
175 } // namespace about_flags
177 #endif // CHROME_BROWSER_ABOUT_FLAGS_H_