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
14class PrefService;
15
16namespace base {
17class ListValue;
18}
19
20namespace about_flags {
21
22class FlagsStorage;
23
24// Enumeration of OSs.
25// This is exposed only for testing.
26enum { 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.
32struct 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.
110enum 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|.
114void 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.
120bool 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.
128enum 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|.
133void 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.
139bool IsRestartNeededToCommitChanges();
140
141// Enables or disables the experiment with id |internal_name|.
142void 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()|.
148void RemoveFlagsSwitches(
149    std::map<std::string, base::CommandLine::StringType>* switch_list);
150
151// Reset all flags to the default state by clearing all flags.
152void 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.
157int GetCurrentPlatform();
158
159// Sends UMA stats about experimental flag usage. This should be called once per
160// startup.
161void RecordUMAStatistics(FlagsStorage* flags_storage);
162
163namespace testing {
164
165// Clears internal global state, for unit tests.
166void 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.
170void SetExperiments(const Experiment* e, size_t count);
171
172// Returns the current set of experiments.
173const 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.
177extern const char kMultiSeparator[];
178
179}  // namespace testing
180
181}  // namespace about_flags
182
183#endif  // CHROME_BROWSER_ABOUT_FLAGS_H_
184