diff options
Diffstat (limited to 'python')
| -rw-r--r-- | python/binaryview.py | 51 | ||||
| -rw-r--r-- | python/settings.py | 75 |
2 files changed, 89 insertions, 37 deletions
diff --git a/python/binaryview.py b/python/binaryview.py index 7e7e323b..5a1741c5 100644 --- a/python/binaryview.py +++ b/python/binaryview.py @@ -639,13 +639,13 @@ class BinaryViewType(with_metaclass(_BinaryViewTypeMetaclass, object)): @classmethod def get_view_of_file(cls, filename, update_analysis=True, progress_func=None): """ - ``get_view_of_file`` opens and returns the first available `BinaryView`, excluding 'Raw' `BinaryViewType`s + ``get_view_of_file`` opens and returns the first available :class:`BinaryView`, excluding *'Raw'* :class:`BinaryViewType`s :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 bool update_analysis: whether or not to run :func:`update_analysis_and_wait` after opening a :class:`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 + :return: returns a :class:`BinaryView` object for the given filename + :rtype: :class:`BinaryView` or ``None`` """ sqlite = b"SQLite format 3" isDatabase = filename.endswith(".bndb") @@ -681,19 +681,19 @@ class BinaryViewType(with_metaclass(_BinaryViewTypeMetaclass, object)): 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 + :class:`BinaryView`, excluding *'Raw'* :class:`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. + .. note:: Calling this method without providing options is not necessarily equivalent to simply calling :func:`get_view_of_file`. Since \ + :class:`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 :func:`get_view_of_file` sets **'loader.imageBase'** to 0, whereas opening with \ + :func:`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 bool update_analysis: whether or not to run :func:`update_analysis_and_wait` after opening a :class:`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 + :return: returns a :class:`BinaryView` object for the given filename + :rtype: :class:`BinaryView` or ``None`` :Example: @@ -5122,6 +5122,13 @@ class BinaryView(object): core.BNBinaryViewRemoveMetadata(self.handle, key) def get_load_settings_type_names(self): + """ + ``get_load_settings_type_names`` retrieve a list :class:`BinaryViewType` names for which load settings exist in \ + this :class:`BinaryView` context + + :return: list of :class:`BinaryViewType` names + :rtype: list(str) + """ result = [] count = ctypes.c_ulonglong(0) names = core.BNBinaryViewGetLoadSettingsTypeNames(self.handle, count) @@ -5131,12 +5138,26 @@ class BinaryView(object): return result def get_load_settings(self, type_name): + """ + ``get_load_settings`` retrieve a :class:`Settings` object which defines the load settings for the given :class:`BinaryViewType` ``type_name`` + + :param str type_name: the :class:`BinaryViewType` name + :return: the load settings + :rtype: :class:`Settings`, or ``None`` + """ settings_handle = core.BNBinaryViewGetLoadSettings(self.handle, type_name) if settings_handle is None: return None return settings.Settings(handle=settings_handle) def set_load_settings(self, type_name, settings): + """ + ``set_load_settings`` set a :class:`Settings` object which defines the load settings for the given :class:`BinaryViewType` ``type_name`` + + :param str type_name: the :class:`BinaryViewType` name + :param Settings settings: the load settings + :rtype: None + """ core.BNBinaryViewSetLoadSettings(self.handle, type_name, settings.handle) def __setattr__(self, name, value): @@ -5155,11 +5176,11 @@ class BinaryView(object): - Symbols are everything in ``bv.symbols``, unnamed DataVariables (i.e. ``data_00005000``), unnamed functions (i.e. ``sub_00005000``), or section names (i.e. ``.text``) - Numbers are defaulted to hexadecimal thus `_printf + 10` is equivalent to `printf + 0x10` If decimal numbers required use the decimal prefix. - Since numbers and symbols can be ambiguous its recommended that you prefix your numbers with the following: - + - ``0x`` - Hexadecimal - ``0n`` - Decimal - ``0`` - Octal - + - In the case of an ambiguous number/symbol (one with no prefix) for instance ``12345`` we will first attempt to look up the string as a symbol, if a symbol is found its address is used, otherwise we attempt to convert it to a hexadecimal number. @@ -5171,7 +5192,7 @@ class BinaryView(object): - ``[<expression>].w`` - read the word (2 bytes) at ``<expression>`` - ``[<expression>].d`` - read the dword (4 bytes) at ``<expression>`` - ``[<expression>].q`` - read the quadword (8 bytes) at ``<expression>`` - + - The ``$here`` keyword can be used in calculations and is defined as the ``here`` parameter - The ``$start``/``$end`` keyword represents the address of the first/last bytes in the file respectively diff --git a/python/settings.py b/python/settings.py index 0c613fe1..fec4023d 100644 --- a/python/settings.py +++ b/python/settings.py @@ -36,30 +36,30 @@ class Settings(object): 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 \ + Each :class:`Settings` instance has a unique ``instance_id`` and a settings schema that define the contents for the settings \ + repository. By default, a new :class:`Settings` instance contains an empty schema. A schema can be built up by using the \ + :func:`register_group` and func:`register_setting` methods, or by deserializing an existing schema with :func:`deserialize_schema`. \ + Binary Ninja provides a default :class:`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. + 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. + 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 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) - =================== ============================ ============================== =============================== + ================= ========================== ============== ================================ =============================== + Setting Level Settings Scope Preference Backing Store ('default') Backing Store (Other) + ================= ========================== ============== ================================ =============================== + Default SettingsDefaultScope Lowest Settings Schema Settings Schema + User SettingsUserScope - <User Directory>/settings.json <TBD> + Workspace SettingsWorkspaceScope - <TBD> <TBD> + Context SettingsContextScope Highest 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. + 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. """ handle = core.BNCreateSettings("default") @@ -95,17 +95,29 @@ class Settings(object): @property def instance_id(self): - """(read-only)""" + """Returns the ``instance_id`` for this :class:`Settings` repository (read-only)""" return self._instance_id def set_resource_id(self, resource_id = None): + """ + ``set_resource_id`` Sets the resource identifier for this class:`Settings` instance. When accessing setting values at the \ + ``SettingsContextScope`` level, the resource identifier is passed along through the backing store interface. + + .. note:: Currently the only available backing store for ``SettingsContextScope`` is a :class:`BinaryView` object. In the context \ + of a :class:`BinaryView` the resource identifier is the :class:`BinaryViewType` name. All settings for this type of backing store \ + are saved in the *'Raw'* :class:`BinaryViewType`. This enables the configuration of setting values such that they are available \ + during :class:`BinaryView` creation and initialization. + + :param str resource_id: a unique identifier + :rtype: None + """ if resource_id is None: resource_id = "" core.BNSettingsSetResourceId(self.handle, resource_id) def register_group(self, group, title): """ - ``register_group`` registers a group in the schema for this `Settings` instance + ``register_group`` registers a group in the schema for this :class:`Settings` instance :param str group: a unique identifier :param str title: a user friendly name appropriate for UI presentation @@ -121,9 +133,9 @@ 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 :class:`Settings` instance - :param str key: a unique setting identifier in the form <group>.<name> + :param str key: a unique setting identifier in the form **'<group>.<name>'** :param str properties: a JSON string describes the setting schema :return: True on success, False on failure. :rtype: bool @@ -137,12 +149,31 @@ class Settings(object): return core.BNSettingsRegisterSetting(self.handle, key, properties) def contains(self, key): + """ + ``contains`` determine if a setting identifier exists in the active settings schema + + :param str key: the setting identifier + :return: True if the identifier exists in this active settings schema, False otherwise + :rtype: bool + """ return core.BNSettingsContains(self.handle, key) def is_empty(self): + """ + ``is_empty`` determine if the active settings schema is empty + + :return: True if the active settings schema is empty, False otherwise + :rtype: bool + """ return core.BNSettingsIsEmpty(self.handle) def keys(self): + """ + ``keys`` retrieve the list of setting identifiers in the active settings schema + + :return: list of setting identifiers + :rtype: list(str) + """ length = ctypes.c_ulonglong() result = core.BNSettingsKeysList(self.handle, ctypes.byref(length)) out_list = [] |