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