Demangler plugin API

Closes #467

Author: CouleeApps

binaryninjaapi.h

@@ -1564,11 +1564,29 @@ namespace BinaryNinja {
 	*/
 	Ref<BinaryView> Load(Ref<BinaryView> rawData, bool updateAnalysis, std::function<bool(size_t, size_t)> progress, Ref<Metadata> options = new Metadata(MetadataType::KeyValueDataType), bool isDatabase = false);
 
+	/*! Attempt to demangle a mangled name, trying all relevant demanglers and using whichever one accepts it
+
+		\see Demangler::Demangle for a discussion on which demangler will be used.
+
+		\param[in] arch Architecture for the symbol. Required for pointer and integer sizes.
+		\param[in] mangledName a mangled Microsoft Visual Studio C++ name
+		\param[out] outType Pointer to Type to output
+		\param[out] outVarName QualifiedName reference to write the output name to.
+		\param[in] view (Optional) view of the binary containing the mangled name
+		\param[in] simplify (Optional) Whether to simplify demangled names.
+		\return True if the name was demangled and written to the out* parameters
+
+		\ingroup demangle
+	*/
+	bool DemangleGeneric(Ref<Architecture> arch, const std::string& mangledName, Ref<Type>& outType, QualifiedName& outVarName,
+	                     Ref<BinaryView> view = nullptr, const bool simplify = false);
+
 	/*! Demangles using LLVM's demangler
 
 		\param[in] mangledName a mangled (msvc/itanium/rust/dlang) name
 		\param[out] outVarName QualifiedName reference to write the output name to.
 		\param[in] simplify Whether to simplify demangled names.
+	    \return True if the name was demangled and written to the out* parameters
 
 		\ingroup demangle
 	*/
@@ -1579,6 +1597,7 @@ namespace BinaryNinja {
 		\param[in] mangledName a mangled (msvc/itanium/rust/dlang) name
 		\param[out] outVarName QualifiedName reference to write the output name to.
 		\param[in] view View to check the analysis.types.templateSimplifier for
+	    \return True if the name was demangled and written to the out* parameters
 
 		\ingroup demangle
 	*/
@@ -1591,6 +1610,7 @@ namespace BinaryNinja {
 	    \param[out] outType Reference to Type to output
 	    \param[out] outVarName QualifiedName reference to write the output name to.
 	    \param[in] simplify Whether to simplify demangled names.
+	    \return True if the name was demangled and written to the out* parameters
 
 	    \ingroup demangle
 	*/
@@ -1607,6 +1627,7 @@ namespace BinaryNinja {
 	    \param[out] outType Reference to Type to output
 	    \param[out] outVarName QualifiedName reference to write the output name to.
 	    \param[in] view View to check the analysis.types.templateSimplifier for
+	    \return True if the name was demangled and written to the out* parameters
 
 	    \ingroup demangle
 	*/
@@ -1620,6 +1641,7 @@ namespace BinaryNinja {
 	    \param[out] outType Reference to Type to output
 	    \param[out] outVarName QualifiedName reference to write the output name to.
 	    \param[in] simplify Whether to simplify demangled names.
+	    \return True if the name was demangled and written to the out* parameters
 
 	    \ingroup demangle
 	*/
@@ -1636,6 +1658,7 @@ namespace BinaryNinja {
 	    \param[out] outType Reference to Type to output
 	    \param[out] outVarName QualifiedName reference to write the output name to.
 	    \param[in] view View to check the analysis.types.templateSimplifier for
+	    \return True if the name was demangled and written to the out* parameters
 
 	    \ingroup demangle
 	*/
@@ -17968,6 +17991,98 @@ namespace BinaryNinja {
 		bool IsAborted();
 	};
 
+	/*!
+		\ingroup demangler
+	*/
+	class Demangler: public StaticCoreRefCountObject<BNDemangler>
+	{
+		std::string m_nameForRegister;
+
+	protected:
+		explicit Demangler(const std::string& name);
+		Demangler(BNDemangler* demangler);
+		virtual ~Demangler() = default;
+
+		static bool IsMangledStringCallback(void* ctxt, const char* name);
+		static bool DemangleCallback(void* ctxt, BNArchitecture* arch, const char* name, BNType** outType,
+			BNQualifiedName* outVarName, BNBinaryView* view);
+		static void FreeVarNameCallback(void* ctxt, BNQualifiedName* name);
+
+	public:
+		/*! Register a custom Demangler. Newly registered demanglers will get priority over
+			previously registered demanglers and built-in demanglers.
+		 */
+		static void Register(Demangler* demangler);
+
+		/*! Get the list of currently registered demanglers, sorted by lowest to highest priority.
+
+			\return List of demanglers
+		 */
+		static std::vector<Ref<Demangler>> GetList();
+		static Ref<Demangler> GetByName(const std::string& name);
+
+		/*! Promote a demangler to the highest-priority position.
+
+			\param demangler Demangler to promote
+		 */
+		static void Promote(Ref<Demangler> demangler);
+
+		std::string GetName() const;
+
+		/*! Determine if a given name is mangled and this demangler can process it
+
+			The most recently registered demangler that claims a name is a mangled string
+			(returns true from this function), and then returns a value from Demangle will
+			determine the result of a call to DemangleGeneric. Returning True from this
+			does not require the demangler to succeed the call to Demangle, but simply
+			implies that it may succeed.
+
+			\param name Raw mangled name string
+			\return True if the demangler thinks it can handle the name
+		 */
+		virtual bool IsMangledString(const std::string& name) = 0;
+
+		/*! Demangle a raw name into a Type and QualifiedName.
+
+			Any unresolved named types referenced by the resulting Type will be created as
+			empty structures or void typedefs in the view, if the result is used on
+			a data structure in the view. Given this, the call to Demangle should NOT
+			cause any side-effects creating types in the view trying to resolve this
+			and instead just return a type with unresolved named type references.
+
+			The most recently registered demangler that claims a name is a mangled string
+			(returns true from IsMangledString), and then returns a value from
+			this function will determine the result of a call to DemangleGeneric.
+			If this call returns None, the next most recently used demangler(s) will be tried instead.
+
+			If the mangled name has no type information, but a name is still possible to extract,
+			this function may return a successful result with outType=nullptr, which will be accepted.
+
+			\param arch Architecture for context in which the name exists, eg for pointer sizes
+			\param name Raw mangled name
+			\param outType Resulting type, if one can be deduced, will be written here. Otherwise nullptr will be written
+			\param outVarName Resulting variable name
+			\param view (Optional) BinaryView context in which the name exists, eg for type lookup
+			\return True if demangling was successful and results were stored into out-parameters
+		 */
+		virtual bool Demangle(Ref<Architecture> arch, const std::string& name, Ref<Type>& outType,
+			QualifiedName& outVarName, Ref<BinaryView> view = nullptr) = 0;
+	};
+
+	/*!
+		\ingroup demangler
+	*/
+	class CoreDemangler: public Demangler
+	{
+	public:
+		CoreDemangler(BNDemangler* demangler);
+		virtual ~CoreDemangler() = default;
+
+		virtual bool IsMangledString(const std::string& name);
+		virtual bool Demangle(Ref<Architecture> arch, const std::string& name, Ref<Type>& outType,
+			QualifiedName& outVarName, Ref<BinaryView> view);
+	};
+
 	namespace Unicode
 	{
 		std::string UTF16ToUTF8(const uint8_t* utf16, const size_t len);

binaryninjacore.h

@@ -297,6 +297,7 @@ extern "C"
 	typedef struct BNCollaborationLazyT BNCollaborationLazyT;
 	typedef struct BNUndoAction BNUndoAction;
 	typedef struct BNUndoEntry BNUndoEntry;
+	typedef struct BNDemangler BNDemangler;
 
 	//! Console log levels
 	typedef enum BNLogLevel
@@ -3323,6 +3324,15 @@ extern "C"
 		void (*freeConflictList)(void* context, BNAnalysisMergeConflict** conflictList, size_t count);
 	} BNAnalysisMergeConflictSplitterCallbacks;
 
+	typedef struct BNDemanglerCallbacks
+	{
+		void* context;
+		bool (*isMangledString)(void* ctxt, const char* name);
+		bool (*demangle)(void* ctxt, BNArchitecture* arch, const char* name, BNType** outType,
+			BNQualifiedName* outVarName, BNBinaryView* view);
+		void (*freeVarName)(void* ctxt, BNQualifiedName* name);
+	} BNDemanglerCallbacks;
+
 	typedef bool(*BNProgressFunction)(void*, size_t, size_t);
 	typedef bool(*BNCollaborationAnalysisConflictHandler)(void*, const char** keys, BNAnalysisMergeConflict** conflicts, size_t conflictCount);
 	typedef bool(*BNCollaborationNameChangesetFunction)(void*, BNCollaborationChangeset*);
@@ -6546,14 +6556,6 @@ extern "C"
 	BINARYNINJACOREAPI BNTypeLibrary** BNGetPlatformTypeLibrariesByName(
 	    BNPlatform* platform, const char* depName, size_t* count);
 
-	// Demangler
-	BINARYNINJACOREAPI bool BNDemangleMS(BNArchitecture* arch, const char* mangledName, BNType** outType,
-	    char*** outVarName, size_t* outVarNameElements, const bool simplify);
-	BINARYNINJACOREAPI bool BNDemangleMSWithOptions(BNArchitecture* arch, const char* mangledName, BNType** outType,
-	    char*** outVarName, size_t* outVarNameElements, const BNBinaryView* const view);
-	BINARYNINJACOREAPI bool BNDemangleMSPlatform(BNPlatform* platform, const char* mangledName, BNType** outType,
-	    char*** outVarName, size_t* outVarNameElements, const bool simplify);
-
 	// Download providers
 	BINARYNINJACOREAPI BNDownloadProvider* BNRegisterDownloadProvider(
 	    const char* name, BNDownloadProviderCallbacks* callbacks);
@@ -6748,6 +6750,14 @@ extern "C"
 	    BNReportCollection* reports, BNBinaryView* view, const char* title, BNFlowGraph* graph);
 	BINARYNINJACOREAPI void BNUpdateReportFlowGraph(BNReportCollection* reports, size_t i, BNFlowGraph* graph);
 
+	// Demangler
+	BINARYNINJACOREAPI bool BNDemangleMS(BNArchitecture* arch, const char* mangledName, BNType** outType,
+	    char*** outVarName, size_t* outVarNameElements, const bool simplify);
+	BINARYNINJACOREAPI bool BNDemangleMSWithOptions(BNArchitecture* arch, const char* mangledName, BNType** outType,
+	    char*** outVarName, size_t* outVarNameElements, const BNBinaryView* const view);
+	BINARYNINJACOREAPI bool BNDemangleMSPlatform(BNPlatform* platform, const char* mangledName, BNType** outType,
+	    char*** outVarName, size_t* outVarNameElements, const bool simplify);
+
 	BINARYNINJACOREAPI bool BNIsGNU3MangledString(const char* mangledName);
 	BINARYNINJACOREAPI bool BNDemangleGNU3(BNArchitecture* arch, const char* mangledName, BNType** outType,
 	    char*** outVarName, size_t* outVarNameElements, const bool simplify);
@@ -6756,11 +6766,24 @@ extern "C"
 	BINARYNINJACOREAPI void BNFreeDemangledName(char*** name, size_t nameElements);
 
 	BINARYNINJACOREAPI bool BNDemangleLLVM(const char* mangledName,
-		char*** outVarName, size_t* outVarNameElements, const bool simplify);
+	    char*** outVarName, size_t* outVarNameElements, const bool simplify);
 	BINARYNINJACOREAPI bool BNDemangleLLVMWithOptions(const char* mangledName,
-	char*** outVarName, size_t* outVarNameElements, const BNBinaryView* const view);
+	    char*** outVarName, size_t* outVarNameElements, const BNBinaryView* const view);
+
+	BINARYNINJACOREAPI BNDemangler* BNRegisterDemangler(const char* name, BNDemanglerCallbacks* callbacks);
+	BINARYNINJACOREAPI BNDemangler** BNGetDemanglerList(size_t* count);
+	BINARYNINJACOREAPI void BNFreeDemanglerList(BNDemangler** demanglers);
+	BINARYNINJACOREAPI BNDemangler* BNGetDemanglerByName(const char* name);
+	BINARYNINJACOREAPI char* BNGetDemanglerName(BNDemangler* demangler);
+	BINARYNINJACOREAPI void BNPromoteDemangler(BNDemangler* demangler);
+
+	BINARYNINJACOREAPI bool BNIsDemanglerMangledName(BNDemangler* demangler, const char* name);
+	BINARYNINJACOREAPI bool BNDemanglerDemangle(BNDemangler* demangler, BNArchitecture* arch, const char* name,
+	    BNType** outType, BNQualifiedName* outVarName, BNBinaryView* view);
+	BINARYNINJACOREAPI bool BNDemangleGeneric(BNArchitecture* arch, const char* name,
+	    BNType** outType, BNQualifiedName* outVarName, BNBinaryView* view, bool simplify);
 
-	// Plugin repository APIs
+// Plugin repository APIs
 	BINARYNINJACOREAPI char** BNPluginGetApis(BNRepoPlugin* p, size_t* count);
 	BINARYNINJACOREAPI const char* BNPluginGetAuthor(BNRepoPlugin* p);
 	BINARYNINJACOREAPI const char* BNPluginGetDescription(BNRepoPlugin* p);

demangle.cpp

@@ -1,8 +1,27 @@
 #include "binaryninjaapi.h"
 #include <string>
 using namespace std;
+using namespace BinaryNinja;
 
 namespace BinaryNinja {
+	bool DemangleGeneric(Ref<Architecture> arch, const std::string& name, Ref<Type>& outType,
+		QualifiedName& outVarName, Ref<BinaryView> view, bool simplify)
+	{
+		BNType* apiType;
+		BNQualifiedName apiVarName;
+		bool success = BNDemangleGeneric(
+			arch->m_object, name.c_str(), &apiType, &apiVarName, view ? view->m_object : nullptr, simplify);
+
+		if (!success)
+			return false;
+
+		if (apiType)
+			outType = new Type(apiType);
+		outVarName = QualifiedName::FromAPIObject(&apiVarName);
+		BNFreeQualifiedName(&apiVarName);
+		return true;
+	}
+
 	bool DemangleLLVM(const std::string& mangledName, QualifiedName& outVarName,
 		BinaryView* view)
 	{
@@ -109,4 +128,120 @@ namespace BinaryNinja {
 		BNFreeQualifiedName(&name);
 		return result;
 	}
+
+	Demangler::Demangler(const std::string& name): m_nameForRegister(name)
+	{
+	}
+
+	Demangler::Demangler(BNDemangler* demangler)
+	{
+		m_object = demangler;
+	}
+
+	bool Demangler::IsMangledStringCallback(void* ctxt, const char* name)
+	{
+		Demangler* demangler = (Demangler*)ctxt;
+		return demangler->IsMangledString(name);
+	}
+
+	bool Demangler::DemangleCallback(void* ctxt, BNArchitecture* arch, const char* name, BNType** outType,
+	                                 BNQualifiedName* outVarName, BNBinaryView* view)
+	{
+		Demangler* demangler = (Demangler*)ctxt;
+
+		Ref<Architecture> apiArch = new CoreArchitecture(arch);
+		Ref<BinaryView> apiView = view ? new BinaryView(BNNewViewReference(view)) : nullptr;
+
+		Ref<Type> apiType;
+		QualifiedName apiVarName;
+		bool success = demangler->Demangle(apiArch, name, apiType, apiVarName, apiView);
+		if (!success)
+			return false;
+
+		if (apiType)
+		{
+			*outType = BNNewTypeReference(apiType->m_object);
+		}
+		else
+		{
+			*outType = nullptr;
+		}
+		*outVarName = apiVarName.GetAPIObject();
+
+		return true;
+	}
+
+	void Demangler::FreeVarNameCallback(void* ctxt, BNQualifiedName* name)
+	{
+		QualifiedName::FreeAPIObject(name);
+	}
+
+	void Demangler::Register(Demangler* demangler)
+	{
+		BNDemanglerCallbacks cb;
+		cb.context = (void*)demangler;
+		cb.isMangledString = IsMangledStringCallback;
+		cb.demangle = DemangleCallback;
+		cb.freeVarName = FreeVarNameCallback;
+		demangler->m_object = BNRegisterDemangler(demangler->m_nameForRegister.c_str(), &cb);
+	}
+
+	std::vector<Ref<Demangler>> Demangler::GetList()
+	{
+		size_t count;
+		BNDemangler** list = BNGetDemanglerList(&count);
+		vector<Ref<Demangler>> result;
+		for (size_t i = 0; i < count; i++)
+			result.push_back(new CoreDemangler(list[i]));
+		BNFreeDemanglerList(list);
+		return result;
+	}
+
+	Ref<Demangler> Demangler::GetByName(const std::string& name)
+	{
+		BNDemangler* result = BNGetDemanglerByName(name.c_str());
+		if (!result)
+			return nullptr;
+		return new CoreDemangler(result);
+	}
+
+	void Demangler::Promote(Ref<Demangler> demangler)
+	{
+		BNPromoteDemangler(demangler->m_object);
+	}
+
+	std::string Demangler::GetName() const
+	{
+		char* name = BNGetDemanglerName(m_object);
+		std::string value = name;
+		BNFreeString(name);
+		return value;
+	}
+
+	CoreDemangler::CoreDemangler(BNDemangler* demangler): Demangler(demangler)
+	{
+	}
+
+	bool CoreDemangler::IsMangledString(const std::string& name)
+	{
+		return BNIsDemanglerMangledName(m_object, name.c_str());
+	}
+
+	bool CoreDemangler::Demangle(Ref<Architecture> arch, const std::string& name, Ref<Type>& outType,
+		QualifiedName& outVarName, Ref<BinaryView> view)
+	{
+		BNType* apiType;
+		BNQualifiedName apiVarName;
+		bool success = BNDemanglerDemangle(
+			m_object, arch->m_object, name.c_str(), &apiType, &apiVarName, view ? view->m_object : nullptr);
+
+		if (!success)
+			return false;
+
+		if (apiType)
+			outType = new Type(apiType);
+		outVarName = QualifiedName::FromAPIObject(&apiVarName);
+		BNFreeQualifiedName(&apiVarName);
+		return true;
+	}
 }  // namespace BinaryNinja