Settings

Detailed Description

Classes
class	BinaryNinja::Settings
	Settings provides a way to define and access settings in a hierarchical fashion. More...

---

Class Documentation

BinaryNinja::Settings

class BinaryNinja::Settings

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"} "elementType" string "type" is "array" No {"string"} "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 "requiresRestart bool None Yes Enable restart notification in the UI upon change ================== ====================================== ================== ======== ======================================================================= \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. More...
void	SetResourceId (const std::string &resourceId="")
	Sets the resource identifier for this Settings instance. More...
bool	RegisterGroup (const std::string &group, const std::string &title)
	Registers a group in the schema for this Settings instance. More...
bool	RegisterSetting (const std::string &key, const std::string &properties)
	Registers a new setting with this Settings instance. More...
bool	Contains (const std::string &key)
	Determine if a setting identifier exists in the active settings schema. More...
bool	IsEmpty ()
	Determine if the active settings schema is empty. More...
std::vector< std::string >	Keys ()
	Retrieve the list of setting identifiers in the active settings schema. More...
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. More...
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. More...
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)
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)
Public Member Functions inherited from BinaryNinja::CoreRefCountObject< BNSettings, BNNewSettingsReference, BNFreeSettings >
	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 Public Member Functions inherited from BinaryNinja::CoreRefCountObject< BNSettings, BNNewSettingsReference, BNFreeSettings >
static BNSettings *	GetObject (CoreRefCountObject *obj)
static BNSettings *	GetObject (const CoreRefCountObject *obj)

Additional Inherited Members
Public Attributes inherited from BinaryNinja::CoreRefCountObject< BNSettings, BNNewSettingsReference, BNFreeSettings >
std::atomic< int >	m_refs
bool	m_registeredRef
BNSettings *	m_object

Constructor & Destructor Documentation

Settings()

Settings::Settings

(

BNSettings *

settings

)

~Settings()

virtual BinaryNinja::Settings::~Settings ( )

inlinevirtual

Member Function Documentation

Instance()

Ref< Settings > Settings::Instance ( const std::string &  schemaId = "" )

static

LoadSettingsFile()

bool Settings::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.

Note

At times it may be useful to make ephemeral changes to settings that are not saved to file. This can be accomplished \ by calling LoadSettingsFile without specifying a filename. This action also resets settings to their default value.

Parameters

fileName	the settings filename
scope	the BNSettingsScope
view	a BinaryView object

Returns

True if the load is successful, False otherwise

SetResourceId()

void Settings::SetResourceId

(

const std::string &

resourceId = ""

)

Sets the resource identifier for this Settings instance.

When accessing setting values at the SettingsResourceScope level, the resource identifier is passed along through the backing store interface.

Note

Currently the only available backing store for SettingsResourceScope is a BinaryView object. In the context of a BinaryView the resource identifier is the BinaryViewType name. All settings for this type of backing store are saved in the 'Raw' BinaryViewType . This enables the configuration of setting values such that they are available during BinaryView creation and initialization.

Parameters

resourceId

a unique identifier

RegisterGroup()

bool Settings::RegisterGroup	(	const std::string &	group,
		const std::string &	title
	)

Registers a group in the schema for this Settings instance.

Parameters

group	a unique identifier
title	a user friendly name appropriate for UI presentation

Returns

True on success, False on failure

RegisterSetting()

bool Settings::RegisterSetting	(	const std::string &	key,
		const std::string &	properties
	)

Registers a new setting with this Settings instance.

Parameters

key	a unique setting identifier in the form '<group>.<name>'
properties	a JSON string describes the setting schema

Returns

True on success, False on failure.

Contains()

bool Settings::Contains

(

const std::string &

key

)

Determine if a setting identifier exists in the active settings schema.

Parameters

key	the setting identifier

Returns

True if the identifier exists in this active settings schema, False otherwise

IsEmpty()

bool Settings::IsEmpty

(

)

Determine if the active settings schema is empty.

Returns

True if the active settings schema is empty, False otherwise

Keys()

vector< string > Settings::Keys

(

)

Retrieve the list of setting identifiers in the active settings schema.

Returns

List of setting identifiers

QueryProperty() [1/2]

template<typename T >

T BinaryNinja::Settings::QueryProperty	(	const std::string &	key,
		const std::string &	property
	)

UpdateProperty() [1/9]

bool Settings::UpdateProperty	(	const std::string &	key,
		const std::string &	property
	)

UpdateProperty() [2/9]

bool Settings::UpdateProperty	(	const std::string &	key,
		const std::string &	property,
		bool	value
	)

UpdateProperty() [3/9]

bool Settings::UpdateProperty	(	const std::string &	key,
		const std::string &	property,
		double	value
	)

UpdateProperty() [4/9]

bool Settings::UpdateProperty	(	const std::string &	key,
		const std::string &	property,
		int	value
	)

UpdateProperty() [5/9]

bool Settings::UpdateProperty	(	const std::string &	key,
		const std::string &	property,
		int64_t	value
	)

UpdateProperty() [6/9]

bool Settings::UpdateProperty	(	const std::string &	key,
		const std::string &	property,
		uint64_t	value
	)

UpdateProperty() [7/9]

bool Settings::UpdateProperty	(	const std::string &	key,
		const std::string &	property,
		const char *	value
	)

UpdateProperty() [8/9]

bool Settings::UpdateProperty	(	const std::string &	key,
		const std::string &	property,
		const std::string &	value
	)

UpdateProperty() [9/9]

bool Settings::UpdateProperty	(	const std::string &	key,
		const std::string &	property,
		const std::vector< std::string > &	value
	)

DeserializeSchema()

bool Settings::DeserializeSchema	(	const std::string &	schema,
		BNSettingsScope	scope = SettingsAutoScope,
		bool	merge = true
	)

SerializeSchema()

string Settings::SerializeSchema

(

)

DeserializeSettings()

bool Settings::DeserializeSettings	(	const std::string &	contents,
		Ref< BinaryView >	view = nullptr,
		BNSettingsScope	scope = SettingsAutoScope
	)

SerializeSettings()

string Settings::SerializeSettings	(	Ref< BinaryView >	view = nullptr,
		BNSettingsScope	scope = SettingsAutoScope
	)

Reset()

bool Settings::Reset	(	const std::string &	key,
		Ref< BinaryView >	view = nullptr,
		BNSettingsScope	scope = SettingsAutoScope
	)

ResetAll()

bool Settings::ResetAll	(	Ref< BinaryView >	view = nullptr,
		BNSettingsScope	scope = SettingsAutoScope,
		bool	schemaOnly = true
	)

Get() [1/7]

template<typename T >

T BinaryNinja::Settings::Get	(	const std::string &	key,
		Ref< BinaryView >	view = nullptr,
		BNSettingsScope *	scope = nullptr
	)

Get the current setting value for a particular key.

bool excludeUnreferencedStrings = Settings::Instance()->Get<bool>("ui.stringView.excludeUnreferencedStrings", data);

Template Parameters

T	type for the value you are retrieving

Parameters

key	Key for the setting
view	BinaryView, for factoring in resource-scoped settings
scope	Scope for the settings

Returns

Value for the setting, with type T

GetJson()

string Settings::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.

string value = Settings::Instance()->GetJson("analysis.mode");
// '"full"'

Parameters

key	Key for the setting
view	BinaryView, for factoring in resource-scoped settings
scope	Scope for the settings

Returns

JSON value for the setting, as a string

Set() [1/8]

bool BinaryNinja::Settings::Set	(	const std::string &	key,
		bool	value,
		Ref< BinaryView >	view = nullptr,
		BNSettingsScope	scope = SettingsAutoScope
	)

Set() [2/8]

bool BinaryNinja::Settings::Set	(	const std::string &	key,
		double	value,
		Ref< BinaryView >	view = nullptr,
		BNSettingsScope	scope = SettingsAutoScope
	)

Set() [3/8]

bool BinaryNinja::Settings::Set	(	const std::string &	key,
		int	value,
		Ref< BinaryView >	view = nullptr,
		BNSettingsScope	scope = SettingsAutoScope
	)

Set() [4/8]

bool BinaryNinja::Settings::Set	(	const std::string &	key,
		int64_t	value,
		Ref< BinaryView >	view = nullptr,
		BNSettingsScope	scope = SettingsAutoScope
	)

Set() [5/8]

bool BinaryNinja::Settings::Set	(	const std::string &	key,
		uint64_t	value,
		Ref< BinaryView >	view = nullptr,
		BNSettingsScope	scope = SettingsAutoScope
	)

Set() [6/8]

bool BinaryNinja::Settings::Set	(	const std::string &	key,
		const char *	value,
		Ref< BinaryView >	view = nullptr,
		BNSettingsScope	scope = SettingsAutoScope
	)

Set() [7/8]

bool BinaryNinja::Settings::Set	(	const std::string &	key,
		const std::string &	value,
		Ref< BinaryView >	view = nullptr,
		BNSettingsScope	scope = SettingsAutoScope
	)

Set() [8/8]

bool BinaryNinja::Settings::Set	(	const std::string &	key,
		const std::vector< std::string > &	value,
		Ref< BinaryView >	view = nullptr,
		BNSettingsScope	scope = SettingsAutoScope
	)

SetJson()

bool Settings::SetJson	(	const std::string &	key,
		const std::string &	value,
		Ref< BinaryView >	view = nullptr,
		BNSettingsScope	scope = SettingsAutoScope
	)

QueryProperty() [2/2]

template<>

vector< string > BinaryNinja::Settings::QueryProperty	(	const string &	key,
		const string &	property
	)

Get() [2/7]

template<>

bool BinaryNinja::Settings::Get	(	const string &	key,
		Ref< BinaryView >	view,
		BNSettingsScope *	scope
	)

Get() [3/7]

template<>

double BinaryNinja::Settings::Get	(	const string &	key,
		Ref< BinaryView >	view,
		BNSettingsScope *	scope
	)

Get() [4/7]

template<>

int64_t BinaryNinja::Settings::Get	(	const string &	key,
		Ref< BinaryView >	view,
		BNSettingsScope *	scope
	)

Get() [5/7]

template<>

uint64_t BinaryNinja::Settings::Get	(	const string &	key,
		Ref< BinaryView >	view,
		BNSettingsScope *	scope
	)

Get() [6/7]

template<>

string BinaryNinja::Settings::Get	(	const string &	key,
		Ref< BinaryView >	view,
		BNSettingsScope *	scope
	)

Get() [7/7]

template<>

vector< string > BinaryNinja::Settings::Get	(	const string &	key,
		Ref< BinaryView >	view,
		BNSettingsScope *	scope
	)