From 04bc6f11ae0289aae57d63d4cd32f4ef305d1a7a Mon Sep 17 00:00:00 2001 From: KyleMiles Date: Thu, 29 Jun 2023 20:49:26 -0400 Subject: Move binary view loading in to the core; deprecate open_view in favor of load; update examples --- binaryninjaapi.h | 496 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 250 insertions(+), 246 deletions(-) (limited to 'binaryninjaapi.h') diff --git a/binaryninjaapi.h b/binaryninjaapi.h index ef47dc23..2170e82f 100644 --- a/binaryninjaapi.h +++ b/binaryninjaapi.h @@ -940,6 +940,239 @@ namespace BinaryNinja { @} */ + class Metadata; + typedef BNMetadataType MetadataType; + + /*! + \ingroup binaryview + */ + class Metadata : public CoreRefCountObject + { + public: + explicit Metadata(BNMetadata* structuredData); + /*! Create a new Metadata object representing a bool + + @threadsafe + + \param data Bool to store + + */ + explicit Metadata(bool data); + + /*! Create a new Metadata object representing a string + + @threadsafe + + \param data string to store + + */ + explicit Metadata(const std::string& data); + + /*! Create a new Metadata object representing a uint64 + + @threadsafe + + \param data - uint64 to store + + */ + explicit Metadata(uint64_t data); + + /*! Create a new Metadata object representing an int64 + + @threadsafe + + \param data - int64 to store + + */ + explicit Metadata(int64_t data); + + /*! Create a new Metadata object representing a double + + @threadsafe + + \param data - double to store + + */ + explicit Metadata(double data); + + /*! Create a new Metadata object representing a vector of bools + + @threadsafe + + \param data - list of bools to store + + */ + explicit Metadata(const std::vector& data); + + /*! Create a new Metadata object representing a vector of strings + + @threadsafe + + \param data - list of strings to store + + */ + explicit Metadata(const std::vector& data); + + /*! Create a new Metadata object representing a vector of uint64s + + @threadsafe + + \param data - list of uint64s to store + + */ + explicit Metadata(const std::vector& data); + + /*! Create a new Metadata object representing a vector of int64s + + @threadsafe + + \param data - list of int64s to store + + */ + explicit Metadata(const std::vector& data); + + /*! Create a new Metadata object representing a vector of doubles + + @threadsafe + + \param data - list of doubles to store + + */ + explicit Metadata(const std::vector& data); + + /*! Create a new Metadata object representing a vector of bytes to store + + @threadsafe + + \param data - list of bytes to store + + */ + explicit Metadata(const std::vector& data); + + /*! Create a new Metadata object representing a vector of children Metadata objects + + @threadsafe + + \param data - list of Metadata objects to store + + */ + explicit Metadata(const std::vector>& data); + + /*! Create a new Metadata object representing a map of strings to metadata objects + + @threadsafe + + \param data - map of strings to metadata objects + + */ + explicit Metadata(const std::map>& data); + explicit Metadata(MetadataType type); + virtual ~Metadata() {} + + bool operator==(const Metadata& rhs); + Ref operator[](const std::string& key); + Ref operator[](size_t idx); + + MetadataType GetType() const; + bool GetBoolean() const; + std::string GetString() const; + uint64_t GetUnsignedInteger() const; + int64_t GetSignedInteger() const; + double GetDouble() const; + std::vector GetBooleanList() const; + std::vector GetStringList() const; + std::vector GetUnsignedIntegerList() const; + std::vector GetSignedIntegerList() const; + std::vector GetDoubleList() const; + std::vector GetRaw() const; + std::vector> GetArray(); + std::map> GetKeyValueStore(); + + // For key-value data only + /*! Get a Metadata object by key. Only for if IsKeyValueStore == true + + @threadunsafewith{SetValueForKey and RemoveKey} + + \param key + \return + */ + Ref Get(const std::string& key); + /*! Set the value mapped to by a particular string. Only for if IsKeyValueStore == true + + @threadunsafewith{Get and RemoveKey} + + \param key + \param data + \return + */ + bool SetValueForKey(const std::string& key, Ref data); + + /*! Remove a key from the map. Only for if IsKeyValueStore == true + + @threadunsafewith{SetValueForKey and Get} + + \param key - Key to remove + */ + void RemoveKey(const std::string& key); + + // For array data only + /*! Get an item at a given index + + For array data only + + @threadunsafewith{Array data modifiers} + + \param index Index of the item to retrieve + \return Item at that index, if valid. + */ + Ref Get(size_t index); + + /*! Append an item to the array + + For array data only + + @threadunsafewith{Array data modifiers} + + \param data Data to append + \return Whether the append was successful + */ + bool Append(Ref data); + + /*! Remove an item at a given index + + For array data only + + @threadunsafewith{Array data modifiers} + + \param index Index of the item to remove + */ + void RemoveIndex(size_t index); + + /*! Get the size of the array + + For array data only + + @threadunsafewith{Array data modifiers} + + \return Size of the array + */ + size_t Size() const; + + bool IsBoolean() const; + bool IsString() const; + bool IsUnsignedInteger() const; + bool IsSignedInteger() const; + bool IsDouble() const; + bool IsBooleanList() const; + bool IsStringList() const; + bool IsUnsignedIntegerList() const; + bool IsSignedIntegerList() const; + bool IsDoubleList() const; + bool IsRaw() const; + bool IsArray() const; + bool IsKeyValueStore() const; + }; + class BinaryView; /*! OpenView opens a file on disk and returns a BinaryView, attempting to use the most @@ -964,60 +1197,62 @@ namespace BinaryNinja { SettingsUserScope and can be modified as follows: \code{.cpp} - Json::Value options(Json::objectValue); - options["files.universal.architecturePreference"] = Json::Value(Json::arrayValue); - options["files.universal.architecturePreference"].append("arm64"); - Ref bv = OpenView("/bin/ls", true, {}, options); + Metadata options = {{"files.universal.architecturePreference", Metadata({"arm64"})}}; + Ref bv = Load("/bin/ls", true, {}, options); \endcode \param filename Path to filename or BNDB to open. \param updateAnalysis If true, UpdateAnalysisAndWait() will be called after opening a BinaryView. \param progress Optional function to be called with progress updates as the view is - being loaded. If the function returns false, it will cancel OpenView. + being loaded. If the function returns false, it will cancel Load. \param options A Json object whose keys are setting identifiers and whose values are the desired settings. \return Constructed view, or a nullptr Ref */ - Ref OpenView(const std::string& filename, bool updateAnalysis = true, std::function progress = {}, Json::Value options = Json::Value(Json::objectValue)); + Ref Load(const std::string& filename, bool updateAnalysis = true, + std::function progress = {}, Ref options = new Metadata(MetadataType::KeyValueDataType)); /*! Open a BinaryView from a raw data buffer, initializing data views and loading settings. @threadmainonly - \see BinaryNinja::OpenView(const std::string&, bool, std::function, Json::Value) + \see BinaryNinja::Load(const std::string&, bool, std::function, Json::Value) for discussion of this function. \param rawData Buffer with raw binary data to load (cannot load from bndb) \param updateAnalysis If true, UpdateAnalysisAndWait() will be called after opening a BinaryView. \param progress Optional function to be called with progress updates as the view is - being loaded. If the function returns false, it will cancel OpenView. + being loaded. If the function returns false, it will cancel Load. \param options A Json object whose keys are setting identifiers and whose values are the desired settings. \return Constructed view, or a nullptr Ref */ - Ref OpenView(const DataBuffer& rawData, bool updateAnalysis = true, std::function progress = {}, Json::Value options = Json::Value(Json::objectValue)); + Ref Load(const DataBuffer& rawData, bool updateAnalysis = true, + std::function progress = {}, Ref options = new Metadata(MetadataType::KeyValueDataType)); /*! Open a BinaryView from a raw BinaryView, initializing data views and loading settings. @threadmainonly - \see BinaryNinja::OpenView(const std::string&, bool, std::function, Json::Value) + \see BinaryNinja::Load(const std::string&, bool, std::function, Json::Value) for discussion of this function. \param rawData BinaryView with raw binary data to load \param updateAnalysis If true, UpdateAnalysisAndWait() will be called after opening a BinaryView. \param progress Optional function to be called with progress updates as the view is - being loaded. If the function returns false, it will cancel OpenView. + being loaded. If the function returns false, it will cancel Load. \param options A Json object whose keys are setting identifiers and whose values are the desired settings. \param isDatabase True if the view being loaded is the raw view of an already opened database. \return Constructed view, or a nullptr Ref */ - Ref OpenView(Ref rawData, bool updateAnalysis = true, std::function progress = {}, Json::Value options = Json::Value(Json::objectValue), bool isDatabase = false); + Ref Load(Ref rawData, bool updateAnalysis = true, + std::function progress = {}, Ref options = new Metadata(MetadataType::KeyValueDataType), + bool isDatabase = false); /*! Demangles a Microsoft Visual Studio C++ name @@ -3251,7 +3486,7 @@ namespace BinaryNinja { To open a file with a given BinaryView the following code is recommended: \code{.cpp} - auto bv = OpenView("/bin/ls"); + auto bv = Load("/bin/ls"); \endcode \remark By convention in the rest of this document we will use bv to mean an open and, analyzed, BinaryView of an executable file. @@ -14446,9 +14681,8 @@ namespace BinaryNinja { "ignore": ["SettingsProjectScope", "SettingsResourceScope"] })~"); - Json::Value options(Json::objectValue); - options["myPlugin.enablePreAnalysis"] = Json::Value(true); - Ref bv = OpenView("/bin/ls", true, {}, options); + Metadata options = {{"myPlugin.enablePreAnalysis", Metadata(true)}}; + Ref bv = Load("/bin/ls", true, {}, options); Settings::Instance()->Get("myPlugin.enablePreAnalysis"); // false Settings::Instance()->Get("myPlugin.enablePreAnalysis", bv); // true @@ -14629,236 +14863,6 @@ namespace BinaryNinja { typedef BNMetadataType MetadataType; - /*! - \ingroup binaryview - */ - class Metadata : public CoreRefCountObject - { - public: - explicit Metadata(BNMetadata* structuredData); - /*! Create a new Metadata object representing a bool - - @threadsafe - - \param data Bool to store - - */ - explicit Metadata(bool data); - - /*! Create a new Metadata object representing a string - - @threadsafe - - \param data string to store - - */ - explicit Metadata(const std::string& data); - - /*! Create a new Metadata object representing a uint64 - - @threadsafe - - \param data - uint64 to store - - */ - explicit Metadata(uint64_t data); - - /*! Create a new Metadata object representing an int64 - - @threadsafe - - \param data - int64 to store - - */ - explicit Metadata(int64_t data); - - /*! Create a new Metadata object representing a double - - @threadsafe - - \param data - double to store - - */ - explicit Metadata(double data); - - /*! Create a new Metadata object representing a vector of bools - - @threadsafe - - \param data - list of bools to store - - */ - explicit Metadata(const std::vector& data); - - /*! Create a new Metadata object representing a vector of strings - - @threadsafe - - \param data - list of strings to store - - */ - explicit Metadata(const std::vector& data); - - /*! Create a new Metadata object representing a vector of uint64s - - @threadsafe - - \param data - list of uint64s to store - - */ - explicit Metadata(const std::vector& data); - - /*! Create a new Metadata object representing a vector of int64s - - @threadsafe - - \param data - list of int64s to store - - */ - explicit Metadata(const std::vector& data); - - /*! Create a new Metadata object representing a vector of doubles - - @threadsafe - - \param data - list of doubles to store - - */ - explicit Metadata(const std::vector& data); - - /*! Create a new Metadata object representing a vector of bytes to store - - @threadsafe - - \param data - list of bytes to store - - */ - explicit Metadata(const std::vector& data); - - /*! Create a new Metadata object representing a vector of children Metadata objects - - @threadsafe - - \param data - list of Metadata objects to store - - */ - explicit Metadata(const std::vector>& data); - - /*! Create a new Metadata object representing a map of strings to metadata objects - - @threadsafe - - \param data - map of strings to metadata objects - - */ - explicit Metadata(const std::map>& data); - explicit Metadata(MetadataType type); - virtual ~Metadata() {} - - bool operator==(const Metadata& rhs); - Ref operator[](const std::string& key); - Ref operator[](size_t idx); - - MetadataType GetType() const; - bool GetBoolean() const; - std::string GetString() const; - uint64_t GetUnsignedInteger() const; - int64_t GetSignedInteger() const; - double GetDouble() const; - std::vector GetBooleanList() const; - std::vector GetStringList() const; - std::vector GetUnsignedIntegerList() const; - std::vector GetSignedIntegerList() const; - std::vector GetDoubleList() const; - std::vector GetRaw() const; - std::vector> GetArray(); - std::map> GetKeyValueStore(); - - // For key-value data only - /*! Get a Metadata object by key. Only for if IsKeyValueStore == true - - @threadunsafewith{SetValueForKey and RemoveKey} - - \param key - \return - */ - Ref Get(const std::string& key); - /*! Set the value mapped to by a particular string. Only for if IsKeyValueStore == true - - @threadunsafewith{Get and RemoveKey} - - \param key - \param data - \return - */ - bool SetValueForKey(const std::string& key, Ref data); - - /*! Remove a key from the map. Only for if IsKeyValueStore == true - - @threadunsafewith{SetValueForKey and Get} - - \param key - Key to remove - */ - void RemoveKey(const std::string& key); - - // For array data only - /*! Get an item at a given index - - For array data only - - @threadunsafewith{Array data modifiers} - - \param index Index of the item to retrieve - \return Item at that index, if valid. - */ - Ref Get(size_t index); - - /*! Append an item to the array - - For array data only - - @threadunsafewith{Array data modifiers} - - \param data Data to append - \return Whether the append was successful - */ - bool Append(Ref data); - - /*! Remove an item at a given index - - For array data only - - @threadunsafewith{Array data modifiers} - - \param index Index of the item to remove - */ - void RemoveIndex(size_t index); - - /*! Get the size of the array - - For array data only - - @threadunsafewith{Array data modifiers} - - \return Size of the array - */ - size_t Size() const; - - bool IsBoolean() const; - bool IsString() const; - bool IsUnsignedInteger() const; - bool IsSignedInteger() const; - bool IsDouble() const; - bool IsBooleanList() const; - bool IsStringList() const; - bool IsUnsignedIntegerList() const; - bool IsSignedIntegerList() const; - bool IsDoubleList() const; - bool IsRaw() const; - bool IsArray() const; - bool IsKeyValueStore() const; - }; - /*! DataRenderer objects tell the Linear View how to render specific types. The `IsValidForData` method returns a boolean to indicate if your derived class -- cgit v1.3.1