diff options
Diffstat (limited to 'python')
| -rw-r--r-- | python/binaryview.py | 42 | ||||
| -rw-r--r-- | python/settings.py | 35 |
2 files changed, 67 insertions, 10 deletions
diff --git a/python/binaryview.py b/python/binaryview.py index 7ff4d4cf..ee4a4fb3 100644 --- a/python/binaryview.py +++ b/python/binaryview.py @@ -639,12 +639,12 @@ class BinaryViewType(with_metaclass(_BinaryViewTypeMetaclass, object)): @classmethod def get_view_of_file(cls, filename, update_analysis=True, progress_func=None): """ - ``get_view_of_file`` returns the first available, non-Raw `BinaryView` available. + ``get_view_of_file`` opens and returns the first available `BinaryView`, excluding 'Raw' `BinaryViewType`s - :param str filename: Path to filename or bndb - :param bool update_analysis: defaults to True. Pass False to not run update_analysis_and_wait. - :param callback progress_func: optional function to be called with the current progress and total count. - :return: returns a BinaryView object for the given filename. + :param str filename: path to filename or bndb to open + :param bool update_analysis: whether or not to run `update_analysis_and_wait` after opening a `BinaryView`, defaults to True + :param callback progress_func: optional function to be called with the current progress and total count + :return: returns a BinaryView object for the given filename :rtype: BinaryView or None """ sqlite = b"SQLite format 3" @@ -678,7 +678,33 @@ class BinaryViewType(with_metaclass(_BinaryViewTypeMetaclass, object)): return bv @classmethod - def get_view_of_file_with_options(cls, filename, update_analysis=True, options={}): + def get_view_of_file_with_options(cls, filename, update_analysis=True, progress_func=None, options={}): + """ + ``get_view_of_file_with_options`` opens, generates default load options (which are overridable), and returns the first available \ + `BinaryView`, excluding 'Raw' `BinaryViewType`s + + .. note:: Calling this method without providing options is not necessarily equivalent to simply calling `get_view_of_file`. Since \ + `BinaryViewType`s are in control of generating load options, this method allows an alternative default way to open a file. For \ + example, opening a relocatable object file with `get_view_of_file` sets 'loader.imageBase' to 0, whereas opening with `get_view_of_file_with_options` \ + sets 'loader.imageBase' to 0x400000 for 64-bit binaries, or 0x10000 for 32-bit binaries, by default. + + :param str filename: path to filename or bndb to open + :param bool update_analysis: whether or not to run `update_analysis_and_wait` after opening a `BinaryView`, defaults to True + :param callback progress_func: optional function to be called with the current progress and total count + :param dict options: a dictionary in the form {str : str}, where key is a setting identifier, and value is a JSON formatted str + :return: returns a BinaryView object for the given filename + :rtype: BinaryView or None + + :Example: + + >>> BinaryViewType.get_view_of_file_with_options('/bin/ls', options={'loader.imageBase': 0xfffffff0000, 'loader.macho.processFunctionStarts' : False}) + <BinaryView: '/bin/ls', start 0xfffffff0000, len 0xa290> + >>> + """ + isDatabase = filename.endswith(".bndb") + if isDatabase: + log.log_warn("Opening a database with options is not yet supported!") + return None view = BinaryView.open(filename) if view is None: return None @@ -1561,9 +1587,9 @@ class BinaryView(object): performing incremental updates and is reset on a full function update. Per-function `update_count` tracks the current number of incremental updates and is reset on a full function update. Per-function `submit_count` tracks the current number of full updates that have completed. - + .. note:: `submit_count` is currently not reset across analysis updates. - + """ info_ref = core.BNGetAnalysisInfo(self.handle) info = info_ref[0] diff --git a/python/settings.py b/python/settings.py index 4521fa78..0c613fe1 100644 --- a/python/settings.py +++ b/python/settings.py @@ -30,6 +30,37 @@ from binaryninja.enums import SettingsScope class Settings(object): + """ + ``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 which defines 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 `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, values are stored separately from the schema in a backing store. The backing store can \ + be different for each level. When accessing setting values, the order of precedence is: Context > Workspace > User > Default. + + =================== ============================ ============================== =============================== + Setting Level Settings Scope Backing Store ('default') Backing Store (Other) + =================== ============================ ============================== =============================== + Default SettingsDefaultScope Settings Schema Settings Schema + User SettingsUserScope <User Directory>/settings.json <TBD> + Workspace SettingsWorkspaceScope <TBD> <TBD> + Context SettingsContextScope BinaryView (Storage in bndb) 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 the same dot \ + notation. + """ handle = core.BNCreateSettings("default") def __init__(self, instance_id = "default", handle = None): @@ -74,7 +105,7 @@ class Settings(object): def register_group(self, group, title): """ - ``register_group`` registers a group for use with this Settings instance. Groups provide a simple way to organize settings. + ``register_group`` registers a group in the schema for this `Settings` instance :param str group: a unique identifier :param str title: a user friendly name appropriate for UI presentation @@ -90,7 +121,7 @@ class Settings(object): def register_setting(self, key, properties): """ - ``register_setting`` registers a new setting with this Settings instance. + ``register_setting`` registers a new setting with this `Settings` instance :param str key: a unique setting identifier in the form <group>.<name> :param str properties: a JSON string describes the setting schema |