Settings
provides a way to define and access settings in a hierarchical fashion.
The value of a setting can be defined for each hierarchical level, where each level overrides the preceding level. The backing-store for setting values at each level is also configurable. This allows for ephemeral or platform-independent persistent settings storage for components within Binary Ninja or consumers of the Binary Ninja API.
Each Settings
instance has an instanceId
which identifies a schema. The schema defines the settings contents and the way in which settings are retrieved and manipulated. A new Settings
instance defaults to using a value of default
for the instanceId
. The default
settings schema defines all of the settings available for the active Binary Ninja components which include at a minimum, the settings defined by the Binary Ninja core. The default
schema may additionally define settings for the UI and/or installed plugins. Extending existing schemas, or defining new ones is accomplished by calling RegisterGroup()
and RegisterSetting()
methods, or by deserializing an existing schema with DeserializeSchema()
.
- Note
- All settings in the
default
settings schema are rendered with UI elements in the Settings View of Binary Ninja UI.
Allowing setting overrides is an important feature and Binary Ninja accomplishes this by allowing one to override a setting at various levels. The levels and their associated storage are shown in the following table. Default setting values are optional, and if specified, saved in the schema itself.
================= ========================== ============== ============================================== Setting Level Settings Scope Preference Storage ================= ========================== ============== ============================================== Default SettingsDefaultScope Lowest Settings Schema User SettingsUserScope - <User Directory>/settings.json Project SettingsProjectScope - <Project Directory>/settings.json Resource SettingsResourceScope Highest Raw BinaryView (Storage in BNDB) ================= ========================== ============== ==============================================
Settings are identified by a key, which is a string in the form of <group>.<name>
or <group>.<subGroup>.<name>
. Groups provide a simple way to categorize settings. Sub-groups are optional and multiple sub-groups are allowed. When defining a settings group, the RegisterGroup
method allows for specifying a UI friendly title for use in the Binary Ninja UI. Defining a new setting requires a unique setting key and a JSON string of property, value pairs. The following table describes the available properties and values.
================== ====================================== ================== ======== ======================================================================= Property JSON Data Type Prerequisite Optional {Allowed Values} and Notes ================== ====================================== ================== ======== ======================================================================= "title" string None No Concise Setting Title "type" string None No {"array", "boolean", "number", "string", "object"} "sorted" boolean "type" is "array" Yes Automatically sort list items (default is false) "isSerialized" boolean "type" is "string" Yes Treat the string as a serialized JSON object "enum" array : {string} "type" is "array" Yes Enumeration definitions "enumDescriptions" array : {string} "type" is "array" Yes Enumeration descriptions that match "enum" array "minValue" number "type" is "number" Yes Specify 0 to infer unsigned (default is signed) "maxValue" number "type" is "number" Yes Values less than or equal to INT_MAX result in a QSpinBox UI element "precision" number "type" is "number" Yes Specify precision for a QDoubleSpinBox "default" {array, boolean, number, string, null} None Yes Specify optimal default value "aliases" array : {string} None Yes Array of deprecated setting key(s) "description" string None No Detailed setting description "ignore" array : {string} None Yes {"SettingsUserScope", "SettingsProjectScope", "SettingsResourceScope"} "message" string None Yes An optional message with additional emphasis "readOnly" bool None Yes Only enforced by UI elements "optional" bool None Yes Indicates setting can be null "hidden" bool "type" is "string" Yes Indicates the UI should conceal the content. The "ignore" property is required to specify the applicable storage scopes "requiresRestart bool None Yes Enable restart notification in the UI upon change
"uiSelectionAction" string "type" is "string" Yes {"file", "directory", <Registered UIAction Name>} Informs the UI to add a button to open a selection dialog or run a registered UIAction
================== ====================================== ================== ======== =======================================================================
\note In order to facilitate deterministic analysis results, settings from the <em><tt>default</tt></em> schema that impact analysis are serialized
from Default, User, and Project scope into Resource scope during initial BinaryView analysis. This allows an analysis database to be opened
at a later time with the same settings, regardless if Default, User, or Project settings have been modified.
\note Settings that do not impact analysis (e.g. many UI settings) should use the \e "ignore" property to exclude
\e "SettingsProjectScope" and \e "SettingsResourceScope" from the applicable scopes for the setting.
<b>Example analysis plugin setting:</b>
@code{.cpp}
auto settings = Settings::Instance()
settings->RegisterGroup("myPlugin", "My Plugin")
settings->RegisterSetting("myPlugin.enablePreAnalysis",
R"~({ "title": "My Pre-Analysis Plugin", "type": "boolean", "default": false, "description": "Enable extra analysis before core analysis.", "ignore": ["SettingsProjectScope", "SettingsResourceScope"] })~");
Metadata options = {{"myPlugin.enablePreAnalysis", Metadata(true)}};
Ref<BinaryView> bv = Load("/bin/ls", true, {}, options);
Settings::Instance()->Get<bool>("myPlugin.enablePreAnalysis"); // false
Settings::Instance()->Get<bool>("myPlugin.enablePreAnalysis", bv); // true
\endcode
<b>Getting a settings value:</b>
@code{.cpp}
bool excludeUnreferencedStrings = Settings::Instance()->Get<bool>("ui.stringView.excludeUnreferencedStrings", bv);
Public Member Functions |
| Settings (BNSettings *settings) |
|
virtual | ~Settings () |
|
bool | LoadSettingsFile (const std::string &fileName, BNSettingsScope scope=SettingsAutoScope, Ref< BinaryView > view=nullptr) |
| Sets the file that this Settings instance uses when initially loading, and modifying \ settings for the specified scope.
|
|
void | SetResourceId (const std::string &resourceId="") |
| Sets the resource identifier for this Settings instance.
|
|
bool | RegisterGroup (const std::string &group, const std::string &title) |
| Registers a group in the schema for this Settings instance.
|
|
bool | RegisterSetting (const std::string &key, const std::string &properties) |
| Registers a new setting with this Settings instance.
|
|
bool | Contains (const std::string &key) |
| Determine if a setting identifier exists in the active settings schema.
|
|
bool | IsEmpty () |
| Determine if the active settings schema is empty.
|
|
std::vector< std::string > | Keys () |
| Retrieve the list of setting identifiers in the active settings schema.
|
|
template<typename T > |
T | QueryProperty (const std::string &key, const std::string &property) |
|
bool | UpdateProperty (const std::string &key, const std::string &property) |
|
bool | UpdateProperty (const std::string &key, const std::string &property, bool value) |
|
bool | UpdateProperty (const std::string &key, const std::string &property, double value) |
|
bool | UpdateProperty (const std::string &key, const std::string &property, int value) |
|
bool | UpdateProperty (const std::string &key, const std::string &property, int64_t value) |
|
bool | UpdateProperty (const std::string &key, const std::string &property, uint64_t value) |
|
bool | UpdateProperty (const std::string &key, const std::string &property, const char *value) |
|
bool | UpdateProperty (const std::string &key, const std::string &property, const std::string &value) |
|
bool | UpdateProperty (const std::string &key, const std::string &property, const std::vector< std::string > &value) |
|
bool | DeserializeSchema (const std::string &schema, BNSettingsScope scope=SettingsAutoScope, bool merge=true) |
|
std::string | SerializeSchema () |
|
bool | DeserializeSettings (const std::string &contents, Ref< BinaryView > view=nullptr, BNSettingsScope scope=SettingsAutoScope) |
|
std::string | SerializeSettings (Ref< BinaryView > view=nullptr, BNSettingsScope scope=SettingsAutoScope) |
|
bool | Reset (const std::string &key, Ref< BinaryView > view=nullptr, BNSettingsScope scope=SettingsAutoScope) |
|
bool | ResetAll (Ref< BinaryView > view=nullptr, BNSettingsScope scope=SettingsAutoScope, bool schemaOnly=true) |
|
template<typename T > |
T | Get (const std::string &key, Ref< BinaryView > view=nullptr, BNSettingsScope *scope=nullptr) |
| Get the current setting value for a particular key.
|
|
std::string | GetJson (const std::string &key, Ref< BinaryView > view=nullptr, BNSettingsScope *scope=nullptr) |
| Get the current settings value for a particular key, as a JSON representation of its value.
|
|
bool | Set (const std::string &key, bool value, Ref< BinaryView > view=nullptr, BNSettingsScope scope=SettingsAutoScope) |
|
bool | Set (const std::string &key, double value, Ref< BinaryView > view=nullptr, BNSettingsScope scope=SettingsAutoScope) |
|
bool | Set (const std::string &key, int value, Ref< BinaryView > view=nullptr, BNSettingsScope scope=SettingsAutoScope) |
|
bool | Set (const std::string &key, int64_t value, Ref< BinaryView > view=nullptr, BNSettingsScope scope=SettingsAutoScope) |
|
bool | Set (const std::string &key, uint64_t value, Ref< BinaryView > view=nullptr, BNSettingsScope scope=SettingsAutoScope) |
|
bool | Set (const std::string &key, const char *value, Ref< BinaryView > view=nullptr, BNSettingsScope scope=SettingsAutoScope) |
|
bool | Set (const std::string &key, const std::string &value, Ref< BinaryView > view=nullptr, BNSettingsScope scope=SettingsAutoScope) |
|
bool | Set (const std::string &key, const std::vector< std::string > &value, Ref< BinaryView > view=nullptr, BNSettingsScope scope=SettingsAutoScope) |
|
bool | SetJson (const std::string &key, const std::string &value, Ref< BinaryView > view=nullptr, BNSettingsScope scope=SettingsAutoScope) |
|
bool | DeserializeSettings (const std::string &contents, Ref< Function > func, BNSettingsScope scope=SettingsAutoScope) |
|
std::string | SerializeSettings (Ref< Function > func, BNSettingsScope scope=SettingsAutoScope) |
|
bool | Reset (const std::string &key, Ref< Function > func, BNSettingsScope scope=SettingsAutoScope) |
|
bool | ResetAll (Ref< Function > func, BNSettingsScope scope=SettingsAutoScope, bool schemaOnly=true) |
|
template<typename T > |
T | Get (const std::string &key, Ref< Function > func, BNSettingsScope *scope=nullptr) |
|
std::string | GetJson (const std::string &key, Ref< Function > func, BNSettingsScope *scope=nullptr) |
|
bool | Set (const std::string &key, bool value, Ref< Function > func, BNSettingsScope scope=SettingsAutoScope) |
|
bool | Set (const std::string &key, double value, Ref< Function > func, BNSettingsScope scope=SettingsAutoScope) |
|
bool | Set (const std::string &key, int value, Ref< Function > func, BNSettingsScope scope=SettingsAutoScope) |
|
bool | Set (const std::string &key, int64_t value, Ref< Function > func, BNSettingsScope scope=SettingsAutoScope) |
|
bool | Set (const std::string &key, uint64_t value, Ref< Function > func, BNSettingsScope scope=SettingsAutoScope) |
|
bool | Set (const std::string &key, const char *value, Ref< Function > func, BNSettingsScope scope=SettingsAutoScope) |
|
bool | Set (const std::string &key, const std::string &value, Ref< Function > func, BNSettingsScope scope=SettingsAutoScope) |
|
bool | Set (const std::string &key, const std::vector< std::string > &value, Ref< Function > func, BNSettingsScope scope=SettingsAutoScope) |
|
bool | SetJson (const std::string &key, const std::string &value, Ref< Function > func, BNSettingsScope scope=SettingsAutoScope) |
|
template<> |
bool | Get (const std::string &key, Ref< Function > func, BNSettingsScope *scope) |
|
template<> |
double | Get (const std::string &key, Ref< Function > func, BNSettingsScope *scope) |
|
template<> |
int64_t | Get (const std::string &key, Ref< Function > func, BNSettingsScope *scope) |
|
template<> |
uint64_t | Get (const std::string &key, Ref< Function > func, BNSettingsScope *scope) |
|
template<> |
string | QueryProperty (const string &key, const string &property) |
|
template<> |
vector< string > | QueryProperty (const string &key, const string &property) |
|
template<> |
bool | Get (const string &key, Ref< BinaryView > view, BNSettingsScope *scope) |
|
template<> |
double | Get (const string &key, Ref< BinaryView > view, BNSettingsScope *scope) |
|
template<> |
int64_t | Get (const string &key, Ref< BinaryView > view, BNSettingsScope *scope) |
|
template<> |
uint64_t | Get (const string &key, Ref< BinaryView > view, BNSettingsScope *scope) |
|
template<> |
string | Get (const string &key, Ref< BinaryView > view, BNSettingsScope *scope) |
|
template<> |
vector< string > | Get (const string &key, Ref< BinaryView > view, BNSettingsScope *scope) |
|
template<> |
bool | Get (const string &key, Ref< Function > func, BNSettingsScope *scope) |
|
template<> |
double | Get (const string &key, Ref< Function > func, BNSettingsScope *scope) |
|
template<> |
int64_t | Get (const string &key, Ref< Function > func, BNSettingsScope *scope) |
|
template<> |
uint64_t | Get (const string &key, Ref< Function > func, BNSettingsScope *scope) |
|
template<> |
string | Get (const string &key, Ref< Function > func, BNSettingsScope *scope) |
|
template<> |
vector< string > | Get (const string &key, Ref< Function > func, BNSettingsScope *scope) |
|
| CoreRefCountObject () |
|
virtual | ~CoreRefCountObject () |
|
BNSettings * | GetObject () const |
|
void | AddRef () |
|
void | Release () |
|
void | AddRefForRegistration () |
|
void | ReleaseForRegistration () |
|
void | AddRefForCallback () |
|
void | ReleaseForCallback () |
|
Static Public Member Functions |
static Ref< Settings > | Instance (const std::string &schemaId="") |
|
static BNSettings * | GetObject (CoreRefCountObject *obj) |
|
static BNSettings * | GetObject (const CoreRefCountObject *obj) |
|