binaryninja.settings.Settings

class Settings(instance_id='default', handle=None)[source]

class 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 is also configurable and can be different for each level. 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 a unique instance_id and a settings schema that define the contents for the settings repository. By default, a new Settings instance contains an empty schema. A schema can be built up by using the register_group and func:register_setting methods, or by deserializing an existing schema with deserialize_schema. Binary Ninja provides a default Settings instance identified as ‘default’. The ‘default’ settings repository defines all of the settings available for the active Binary Ninja components.

Note

The Binary Ninja Application provides many settings that are only applicable to the UI, and thus would not be defined in the ‘default’ settings schema for Binary Ninja headless.

Except for default setting values, setting values are optional for other levels and stored separately from the schema in a backing store. The backing store can be different for each level. When querying setting values, the values returned or modified are in order of preference (i.e. SettingsAutoScope). It is possible to override the scope by specifying the desired SettingsScope.

Setting Level

Settings Scope

Preference

Storage

Default

SettingsDefaultScope

Lowest

Settings Schema

User

SettingsUserScope

<User Directory>/settings.json

Project

SettingsProjectScope

<Project Directory>/.binaryninja/settings.json

Resource

SettingsResourceScope

Highest

BinaryView (Storage in BNDB)

Individual settings are identified by a key, which is a string in the form of ‘<group>.<name>’. Groups provide a simple way to categorize settings. Additionally, sub-categories can be expressed directly in the name part of the key with a similar dot notation.

Here’s a simple example using a Resource Scope to cause settings to be saved inside of a BNDB when saved:

>>> bv2 = open_view("/tmp/ls")
>>> plugin_settings = Settings()
>>> description = "Tells Zhu Li to do the thing."
>>> title = "Do the thing"
>>> schema = f'{{"description" : "{description}", "title" : "{title}", "default" : true, "type" : "boolean"}}'
>>> plugin_settings.register_setting("ui.dothething", schema)
True
>>> plugin_settings.set_bool("ui.dothething", False, bv, SettingsScope.SettingsResourceScope)
True
>>> # Resource scope will save the setting in the BNDB itself
>>> bv2.create_database("/tmp/ls.bndb")
True
>>> bv = open_view("/tmp/ls")
>>> # If in a plugin we would need to make sure we re-regsitered the setting before querying
>>> plugin_settings.get_bool("ui.dothething", bv)
True
>>> bv = binaryninja.open_view("/tmp/ls.bndb")
>>> plugin_settings.get_bool("ui.dothething", bv)
False
__init__(instance_id='default', handle=None)[source]

Initialize self. See help(type(self)) for accurate signature.

Methods

__init__([instance_id, handle])

Initialize self.

contains(key)

contains determine if a setting identifier exists in the active settings schema

deserialize_schema(schema[, scope, merge])

deserialize_settings(contents[, view, scope])

get_bool(key[, view])

get_bool_with_scope(key[, view, scope])

get_double(key[, view])

get_double_with_scope(key[, view, scope])

get_integer(key[, view])

get_integer_with_scope(key[, view, scope])

get_json(key[, view])

get_json_with_scope(key[, view, scope])

get_string(key[, view])

get_string_list(key[, view])

get_string_list_with_scope(key[, view, scope])

get_string_with_scope(key[, view, scope])

is_empty()

is_empty determine if the active settings schema is empty

keys()

keys retrieve the list of setting identifiers in the active settings schema

query_property_string_list(key, property_name)

register_group(group, title)

register_group registers a group in the schema for this Settings instance

register_setting(key, properties)

register_setting registers a new setting with this Settings instance

reset(key[, view, scope])

reset_all([view, scope, schema_only])

serialize_schema()

serialize_settings([view, scope])

set_bool(key, value[, view, scope])

set_double(key, value[, view, scope])

set_integer(key, value[, view, scope])

set_json(key, value[, view, scope])

set_resource_id([resource_id])

set_resource_id Sets the resource identifier for this class:Settings instance.

set_string(key, value[, view, scope])

set_string_list(key, value[, view, scope])

update_property(key, setting_property)

Attributes

handle

instance_id

Returns the instance_id for this Settings repository (read-only)