diff options
Diffstat (limited to 'binaryninjaapi.h')
| -rw-r--r-- | binaryninjaapi.h | 315 |
1 files changed, 315 insertions, 0 deletions
diff --git a/binaryninjaapi.h b/binaryninjaapi.h index ccf72b0a..70f7b97e 100644 --- a/binaryninjaapi.h +++ b/binaryninjaapi.h @@ -2809,6 +2809,7 @@ namespace BinaryNinja { struct TypeParserResult; class Component; class DebugInfo; + class TypeLibrary; class QueryMetadataException : public std::exception { @@ -4459,6 +4460,91 @@ namespace BinaryNinja { void RegisterPlatformTypes(Platform* platform); + /*! Make the contents of a type library available for type/import resolution + + \param lib library to register with the view + */ + void AddTypeLibrary(TypeLibrary* lib); + /*! Get the type library with the given name + + \param name Library name to lookup + \return The Type Library object, or nullptr if one has not been added with this name + */ + Ref<TypeLibrary> GetTypeLibrary(const std::string& name); + /*! Get the list of imported type libraries + + \return All imported type libraries + */ + std::vector<Ref<TypeLibrary>> GetTypeLibraries(); + + /*! Recursively imports a type from the specified type library, or, if no library was explicitly provided, + the first type library associated with the current `BinaryView` that provides the name requested. + + This may have the impact of loading other type libraries as dependencies on other type libraries are lazily resolved + when references to types provided by them are first encountered. + + Note that the name actually inserted into the view may not match the name as it exists in the type library in + the event of a name conflict. To aid in this, the `Type` object returned is a `NamedTypeReference` to + the deconflicted name used. + + \param lib + \param name + \return A `NamedTypeReference` to the type, taking into account any renaming performed + */ + Ref<Type> ImportTypeLibraryType(Ref<TypeLibrary>& lib, const QualifiedName& name); + /*! Recursively imports an object from the specified type library, or, if no library was explicitly provided, + the first type library associated with the current `BinaryView` that provides the name requested. + + This may have the impact of loading other type libraries as dependencies on other type libraries are lazily resolved + when references to types provided by them are first encountered. + + .. note:: If you are implementing a custom BinaryView and use this method to import object types, + you should then call ``RecordImportedObjectLibrary`` with the details of where the object is located. + + \param lib + \param name + \return The object type, with any interior `NamedTypeReferences` renamed as necessary to be appropriate for the current view + */ + Ref<Type> ImportTypeLibraryObject(Ref<TypeLibrary>& lib, const QualifiedName& name); + + /*! Recursively exports ``type`` into ``lib`` as a type with name ``name`` + + As other referenced types are encountered, they are either copied into the destination type library or + else the type library that provided the referenced type is added as a dependency for the destination library. + + \param lib + \param name + \param type + */ + void ExportTypeToTypeLibrary(TypeLibrary* lib, const QualifiedName& name, Type* type); + /*! Recursively exports ``type`` into ``lib`` as an object with name ``name`` + + As other referenced types are encountered, they are either copied into the destination type library or + else the type library that provided the referenced type is added as a dependency for the destination library. + + \param lib + \param name + \param type + */ + void ExportObjectToTypeLibrary(TypeLibrary* lib, const QualifiedName& name, Type* type); + + /*! Should be called by custom `BinaryView` implementations when they have successfully imported an object + from a type library (eg a symbol's type). Values recorded with this function will then be queryable via ``LookupImportedObjectLibrary``. + + \param tgtPlatform Platform of symbol at import site + \param tgtAddr Address of symbol at import site + \param lib Type Library containing the imported type + \param name Name of the object in the type library + */ + void RecordImportedObjectLibrary(Platform* tgtPlatform, uint64_t tgtAddr, TypeLibrary* lib, const QualifiedName& name); + /*! Gives you details of which type library and name was used to determine the type of a symbol at a given address. + + \param tgtPlatform Platform of symbol at import site + \param tgtAddr Address of symbol at import site + \return A pair with the library and name used, or std::nullopt if it was not imported + */ + std::optional<std::pair<Ref<TypeLibrary>, QualifiedName>> LookupImportedObjectLibrary(Platform* tgtPlatform, uint64_t tgtAddr); + bool FindNextData( uint64_t start, const DataBuffer& data, uint64_t& result, BNFindFlag flags = FindCaseSensitive); bool FindNextText(uint64_t start, const std::string& data, uint64_t& result, Ref<DisassemblySettings> settings, @@ -6203,6 +6289,9 @@ namespace BinaryNinja { \return Architecture standalone platform */ Ref<Platform> GetStandalonePlatform(); + + std::vector<Ref<TypeLibrary>> GetTypeLibraries(); + void AddArchitectureRedirection(Architecture* from, Architecture* to); }; @@ -11495,6 +11584,12 @@ namespace BinaryNinja { \return A list of system calls for this platform */ std::map<uint32_t, QualifiedNameAndType> GetSystemCalls(); + + std::vector<Ref<TypeLibrary>> GetTypeLibraries(); + + std::vector<Ref<TypeLibrary>> GetTypeLibrariesByName(const std::string& name); + + Ref<Type> GetTypeByName(const QualifiedName& name); Ref<Type> GetVariableByName(const QualifiedName& name); Ref<Type> GetFunctionByName(const QualifiedName& name, bool exactMatch = false); @@ -13456,4 +13551,224 @@ namespace BinaryNinja { std::vector<DataVariable> GetReferencedDataVariables(); }; + class TypeLibrary: public CoreRefCountObject<BNTypeLibrary, BNNewTypeLibraryReference, BNFreeTypeLibrary> + { + public: + TypeLibrary(BNTypeLibrary* handle); + + /*! Creates an empty type library object with a random GUID and the provided name. + + \param arch + \param name + */ + TypeLibrary(Ref<Architecture> arch, const std::string& name); + + /*! Loads a finalized type library instance from file + + \param path + \return + */ + static Ref<TypeLibrary> LoadFromFile(const std::string& path); + + /*! Looks up the first type library found with a matching name. Keep in mind that names are + not necessarily unique. + + \param arch + \param name + \return + */ + static Ref<TypeLibrary> LookupByName(Ref<Architecture> arch, const std::string& name); + + /*! Attempts to grab a type library associated with the provided Architecture and GUID pair + + \param arch + \param guid + \return + */ + static Ref<TypeLibrary> LookupByGuid(Ref<Architecture> arch, const std::string& guid); + + /*! Saves a finalized type library instance to file + + \param path + */ + void WriteToFile(const std::string& path); + + /*! The Architecture this type library is associated with + + \return + */ + Ref<Architecture> GetArchitecture(); + + /*! Returns the GUID associated with the type library + + \return + */ + std::string GetGuid(); + + /*! The primary name associated with this type library + + \return + */ + std::string GetName(); + + /*! A list of extra names that will be considered a match by ``Platform::GetTypeLibrariesByName`` + + \return + */ + std::set<std::string> GetAlternateNames(); + + /*! The dependency name of a library is the name used to record dependencies across + type libraries. This allows, for example, a library with the name "musl_libc" to have + dependencies on it recorded as "libc_generic", allowing a type library to be used across + multiple platforms where each has a specific libc that also provides the name "libc_generic" + as an `alternate_name`. + + \return + */ + std::string GetDependencyName(); + + /*! Returns a list of all platform names that this type library will register with during platform + type registration. + + This returns strings, not Platform objects, as type libraries can be distributed with support for + Platforms that may not be present. + + \return + */ + std::set<std::string> GetPlatformNames(); + + /*! Retrieves a metadata associated with the given key stored in the type library + + \param key Key to query + \return Metadata associated with the key + */ + Ref<Metadata> QueryMetadata(const std::string& key); + + /*! Sets the GUID of a type library instance that has not been finalized + + \param guid + */ + void SetGuid(const std::string& guid); + + /*! Direct extracts a reference to a contained object -- when attempting to extract types from a library + into a BinaryView, consider using BinaryView::ImportLibraryObject instead. + + \param name + \return + */ + Ref<Type> GetNamedObject(const QualifiedName& name); + + /*! Direct extracts a reference to a contained type -- when attempting to extract types from a library + into a BinaryView, consider using BinaryView.ImportLibraryType>` instead. + + \param name + \return + */ + Ref<Type> GetNamedType(const QualifiedName& name); + + /*! A list containing all named objects (functions, exported variables) provided by a type library + + \return + */ + std::vector<QualifiedNameAndType> GetNamedObjects(); + + /*! A list containing all named types provided by a type library + + \return + */ + std::vector<QualifiedNameAndType> GetNamedTypes(); + + /*! Sets the name of a type library instance that has not been finalized + + \param name + */ + void SetName(const std::string& name); + + /*! Adds an extra name to this type library used during library lookups and dependency resolution + + \param alternate + */ + void AddAlternateName(const std::string& alternate); + + /*! Sets the dependency name of a type library instance that has not been finalized + + \param depName + */ + void SetDependencyName(const std::string& depName); + + /*! Clears the list of platforms associated with a type library instance that has not been finalized + + */ + void ClearPlatforms(); + + /*! Associate a platform with a type library instance that has not been finalized. + + This will cause the library to be searchable by Platform::GetTypeLibrariesByName when loaded. + + This does not have side affects until finalization of the type library. + + \param platform + */ + void AddPlatform(Ref<Platform> platform); + + /*! Stores an object for the given key in the current type library. Objects stored using StoreMetadata can be + retrieved from any reference to the library. + + This is primarily intended as a way to store Platform specific information relevant to BinaryView implementations; + for example the PE BinaryViewType uses type library metadata to retrieve ordinal information, when available. + + \param key Key value to associate the Metadata object with + \param value Object to store. + */ + void StoreMetadata(const std::string& key, Ref<Metadata> value); + + /*! Removes the metadata associated with key from the current type library. + + \param key Key associated with metadata + */ + void RemoveMetadata(const std::string& key); + + /*! Directly inserts a named object into the type library's object store. + This is not done recursively, so care should be taken that types referring to other types + through NamedTypeReferences are already appropriately prepared. + + To add types and objects from an existing BinaryView, it is recommended to use + BinaryView::ExportObjectToLibrary, which will automatically pull in all referenced types and record + additional dependencies as needed. + + \param name + \param type + */ + void AddNamedObject(const QualifiedName& name, Ref<Type> type); + + /*! Directly inserts a named object into the type library's object store. + This is not done recursively, so care should be taken that types referring to other types + through NamedTypeReferences are already appropriately prepared. + + To add types and objects from an existing BinaryView, it is recommended to use + BinaryView::ExportTypeToLibrary, which will automatically pull in all referenced types and record + additional dependencies as needed. + + \param name + \param type + */ + void AddNamedType(const QualifiedName& name, Ref<Type> type); + + /*! Manually flag NamedTypeReferences to the given QualifiedName as originating from another source + TypeLibrary with the given dependency name. + + \warning Use this api with extreme caution. + + \param name + \param source + */ + void AddNamedTypeSource(const QualifiedName& name, const std::string& source); + + /*! Flags a newly created type library instance as finalized and makes it available for Platform and Architecture + type library searches + + */ + void Finalize(); + }; + } // namespace BinaryNinja |