about_flags.h revision 5821806d5e7f356e8fa4b058a389a808ea183019 
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
13class PrefService;
14
15namespace base {
16class ListValue;
17}
18
19namespace about_flags {
20
21// Enumeration of OSs.
22// This is exposed only for testing.
23enum { 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.
29struct 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|.
90void ConvertFlagsToSwitches(PrefService* prefs, CommandLine* command_line);
91
92// Get a list of all available experiments. The caller owns the result.
93base::ListValue* GetFlagsExperimentsData(PrefService* prefs);
94
95// Returns true if one of the experiment flags has been flipped since startup.
96bool IsRestartNeededToCommitChanges();
97
98// Enables or disables the experiment with id |internal_name|.
99void 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()|.
104void 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.
110int GetCurrentPlatform();
111
112// Sends UMA stats about experimental flag usage. This should be called once per
113// startup.
114void RecordUMAStatistics(const PrefService* prefs);
115
116namespace testing {
117// Clears internal global state, for unit tests.
118void 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.
122void SetExperiments(const Experiment* e, size_t count);
123
124// Returns the current set of experiments.
125const 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.
129extern const char kMultiSeparator[];
130
131}  // namespace testing
132
133}  // namespace about_flags
134
135#endif  // CHROME_BROWSER_ABOUT_FLAGS_H_
136