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 <stdint.h> 9 10#include <map> 11#include <set> 12#include <string> 13 14#include "base/command_line.h" 15#include "base/metrics/histogram_base.h" 16#include "base/strings/string16.h" 17 18class PrefService; 19 20namespace base { 21class ListValue; 22} 23 24namespace about_flags { 25 26class FlagsStorage; 27 28// This value is reported as switch histogram ID if switch name has unknown 29// format. 30extern const base::HistogramBase::Sample kBadSwitchFormatHistogramId; 31 32// Enumeration of OSs. 33// This is exposed only for testing. 34enum { kOsMac = 1 << 0, kOsWin = 1 << 1, kOsLinux = 1 << 2 , kOsCrOS = 1 << 3, 35 kOsAndroid = 1 << 4, kOsCrOSOwnerOnly = 1 << 5 }; 36 37// Experiment is used internally by about_flags to describe an experiment (and 38// for testing). 39// This is exposed only for testing. 40struct Experiment { 41 enum Type { 42 // An experiment with a single value. This is typically what you want. 43 SINGLE_VALUE, 44 45 // The experiment has multiple values only one of which is ever enabled. 46 // The first of the values should correspond to a deactivated state for this 47 // lab (i.e. no command line option). For MULTI_VALUE experiments the 48 // command_line of the Experiment is not used. If the experiment is enabled 49 // the command line of the selected Choice is enabled. 50 MULTI_VALUE, 51 52 // The experiment has three possible values: Default, Enabled and Disabled. 53 // This should be used for experiments that may have their own logic to 54 // decide if the feature should be on when not explicitly specified via 55 // about flags - for example via FieldTrials. 56 ENABLE_DISABLE_VALUE, 57 }; 58 59 // Used for MULTI_VALUE types to describe one of the possible values the user 60 // can select. 61 struct Choice { 62 // ID of the message containing the choice name. 63 int description_id; 64 65 // Command line switch and value to enabled for this choice. 66 const char* command_line_switch; 67 // Simple switches that have no value should use "" for command_line_value. 68 const char* command_line_value; 69 }; 70 71 // The internal name of the experiment. This is never shown to the user. 72 // It _is_ however stored in the prefs file, so you shouldn't change the 73 // name of existing flags. 74 const char* internal_name; 75 76 // String id of the message containing the experiment's name. 77 int visible_name_id; 78 79 // String id of the message containing the experiment's description. 80 int visible_description_id; 81 82 // The platforms the experiment is available on 83 // Needs to be more than a compile-time #ifdef because of profile sync. 84 unsigned supported_platforms; // bitmask 85 86 // Type of experiment. 87 Type type; 88 89 // The commandline switch and value that are added when this flag is active. 90 // This is different from |internal_name| so that the commandline flag can be 91 // renamed without breaking the prefs file. 92 // This is used if type is SINGLE_VALUE or ENABLE_DISABLE_VALUE. 93 const char* command_line_switch; 94 // Simple switches that have no value should use "" for command_line_value. 95 const char* command_line_value; 96 97 // For ENABLE_DISABLE_VALUE, the command line switch and value to explictly 98 // disable the feature. 99 const char* disable_command_line_switch; 100 const char* disable_command_line_value; 101 102 // This is used if type is MULTI_VALUE. 103 const Choice* choices; 104 105 // Number of |choices|. 106 // This is used if type is MULTI_VALUE. 107 int num_choices; 108 109 // Returns the name used in prefs for the choice at the specified |index|. 110 std::string NameForChoice(int index) const; 111 112 // Returns the human readable description for the choice at |index|. 113 base::string16 DescriptionForChoice(int index) const; 114}; 115 116// A flag controlling the behavior of the |ConvertFlagsToSwitches| function - 117// whether it should add the sentinel switches around flags. 118enum SentinelsMode { kNoSentinels, kAddSentinels }; 119 120// Reads the Labs |prefs| (called "Labs" for historical reasons) and adds the 121// commandline flags belonging to the active experiments to |command_line|. 122void ConvertFlagsToSwitches(FlagsStorage* flags_storage, 123 base::CommandLine* command_line, 124 SentinelsMode sentinels); 125 126// Compares a set of switches of the two provided command line objects and 127// returns true if they are the same and false otherwise. 128// If |out_difference| is not NULL, it's filled with set_symmetric_difference 129// between sets. 130bool AreSwitchesIdenticalToCurrentCommandLine( 131 const base::CommandLine& new_cmdline, 132 const base::CommandLine& active_cmdline, 133 std::set<CommandLine::StringType>* out_difference); 134 135// Differentiate between generic flags available on a per session base and flags 136// that influence the whole machine and can be said by the admin only. This flag 137// is relevant for ChromeOS for now only and dictates whether entries marked 138// with the |kOsCrOSOwnerOnly| label should be enabled in the UI or not. 139enum FlagAccess { kGeneralAccessFlagsOnly, kOwnerAccessToFlags }; 140 141// Get the list of experiments. Experiments that are available on the current 142// platform are appended to |supported_experiments|; all other experiments are 143// appended to |unsupported_experiments|. 144void GetFlagsExperimentsData(FlagsStorage* flags_storage, 145 FlagAccess access, 146 base::ListValue* supported_experiments, 147 base::ListValue* unsupported_experiments); 148 149// Returns true if one of the experiment flags has been flipped since startup. 150bool IsRestartNeededToCommitChanges(); 151 152// Enables or disables the experiment with id |internal_name|. 153void SetExperimentEnabled(FlagsStorage* flags_storage, 154 const std::string& internal_name, 155 bool enable); 156 157// Removes all switches that were added to a command line by a previous call to 158// |ConvertFlagsToSwitches()|. 159void RemoveFlagsSwitches( 160 std::map<std::string, base::CommandLine::StringType>* switch_list); 161 162// Reset all flags to the default state by clearing all flags. 163void ResetAllFlags(FlagsStorage* flags_storage); 164 165// Returns the value for the current platform. This is one of the values defined 166// by the OS enum above. 167// This is exposed only for testing. 168int GetCurrentPlatform(); 169 170// Sends UMA stats about experimental flag usage. This should be called once per 171// startup. 172void RecordUMAStatistics(FlagsStorage* flags_storage); 173 174// Returns the UMA id for the specified switch name. 175base::HistogramBase::Sample GetSwitchUMAId(const std::string& switch_name); 176 177// Sends stats (as UMA histogram) about command_line_difference. 178// This is used on ChromeOS to report flags that lead to browser restart. 179// |command_line_difference| is the result of 180// AreSwitchesIdenticalToCurrentCommandLine(). 181void ReportCustomFlags(const std::string& uma_histogram_hame, 182 const std::set<std::string>& command_line_difference); 183 184namespace testing { 185 186// Clears internal global state, for unit tests. 187void ClearState(); 188 189// Sets the list of experiments. Pass in NULL to use the default set. This does 190// NOT take ownership of the supplied Experiments. 191void SetExperiments(const Experiment* e, size_t count); 192 193// Returns the current set of experiments. 194const Experiment* GetExperiments(size_t* count); 195 196// Separator used for multi values. Multi values are represented in prefs as 197// name-of-experiment + kMultiSeparator + selected_index. 198extern const char kMultiSeparator[]; 199 200} // namespace testing 201 202} // namespace about_flags 203 204#endif // CHROME_BROWSER_ABOUT_FLAGS_H_ 205