Deprecate Workflow::Instance in favor of Workflow::Get and Workflow::GetOrCreate

Calls to `Workflow::Instance` that were looking up a built-in workflow
name are updated to use `Workflow::Get`. Others use `Workflow::GetOrCreate`.

Author: bdash

binaryninjaapi.h

@@ -11307,13 +11307,43 @@ namespace BinaryNinja {
 		*/
 		static std::vector<Ref<Workflow>> GetList();
 
-		/*! Get an instance of a workflow by name. If it is already registered, this will return the registered Workflow.
-			If not, it will create and return a new Workflow.
+		/*! Get an instance of an existing registered workflow by name.
+			If no registered workflow exists, nullptr will be returned.
+
+			\note Be sure to handle the nullptr case if you're retrieving
+				anything other than a built-in workflow.
 
 			\param name Workflow name
-			\return The registered workflow.
+			\return The registered workflow, or nullptr if none exists.
 		*/
-		static Ref<Workflow> Instance(const std::string& name = "");
+		static Ref<Workflow> Get(const std::string& name);
+
+		/*! Get an instance of a workflow by name. If it is already registered,
+			this will return the registered Workflow. If not, a new Workflow will
+			be created and returned.
+
+			\note If a new workflow is returned it will have no activities. Attempting
+			to register new activities on it via `Insert` and `InsertAfter` will fail.
+
+			\param name Workflow name
+			\return The workflow.
+		*/
+		static Ref<Workflow> GetOrCreate(const std::string& name);
+
+		/*! Get an instance of a workflow by name. If it is already registered,
+			this will return the registered Workflow. If not, a new Workflow will
+			be created and returned.
+
+			\deprecated Use `Get` or `GetOrCreate` instead.
+
+			\note If a new workflow is returned it will have no activities. Attempting
+			to register new activities on it via `Insert` and `InsertAfter` will fail.
+
+			\param name Workflow name
+			\return The workflow.
+		*/
+		static Ref<Workflow> Instance(const std::string& name = "") { return GetOrCreate(name); }
+
 		/*! Register a workflow, making it immutable and available for use
 
 			\param workflow The workflow to register

binaryninjacore.h

@@ -37,14 +37,14 @@
 // Current ABI version for linking to the core. This is incremented any time
 // there are changes to the API that affect linking, including new functions,
 // new types, or modifications to existing functions or types.
-#define BN_CURRENT_CORE_ABI_VERSION 129
+#define BN_CURRENT_CORE_ABI_VERSION 130
 
 // Minimum ABI version that is supported for loading of plugins. Plugins that
 // are linked to an ABI version less than this will not be able to load and
 // will require rebuilding. The minimum version is increased when there are
 // incompatible changes that break binary compatibility, such as changes to
 // existing types or functions.
-#define BN_MINIMUM_CORE_ABI_VERSION 128
+#define BN_MINIMUM_CORE_ABI_VERSION 130
 
 #ifdef __GNUC__
 	#ifdef BINARYNINJACORE_LIBRARY
@@ -5757,7 +5757,8 @@ extern "C"
 
 	BINARYNINJACOREAPI BNWorkflow** BNGetWorkflowList(size_t* count);
 	BINARYNINJACOREAPI void BNFreeWorkflowList(BNWorkflow** workflows, size_t count);
-	BINARYNINJACOREAPI BNWorkflow* BNWorkflowInstance(const char* name);
+	BINARYNINJACOREAPI BNWorkflow* BNWorkflowGet(const char* name);
+	BINARYNINJACOREAPI BNWorkflow* BNWorkflowGetOrCreate(const char* name);
 	BINARYNINJACOREAPI bool BNRegisterWorkflow(BNWorkflow* workflow, const char* configuration);
 
 	BINARYNINJACOREAPI BNWorkflow* BNWorkflowClone(BNWorkflow* workflow, const char* name, const char* activity);

examples/workflows/inliner/inliner.cpp

@@ -158,7 +158,7 @@ extern "C"
 		    },
 		    inlinerIsValid);
 
-		Ref<Workflow> inlinerWorkflow = Workflow::Instance("core.function.baseAnalysis")->Clone("InlinerWorkflow");
+		Ref<Workflow> inlinerWorkflow = Workflow::Get("core.function.baseAnalysis")->Clone("InlinerWorkflow");
 		inlinerWorkflow->RegisterActivity(new Activity("extension.functionInliner", &FunctionInliner));
 		inlinerWorkflow->Insert("core.function.translateTailCalls", "extension.functionInliner");
 		Workflow::RegisterWorkflow(inlinerWorkflow,

examples/workflows/tailcall/tailcall.cpp

@@ -117,7 +117,7 @@ extern "C"
 
 	BINARYNINJAPLUGIN bool CorePluginInit()
 	{
-		Ref<Workflow> customTailCallWorkflow = Workflow::Instance("core.function.baseAnalysis")->Clone("CustomTailCallWorkflow");
+		Ref<Workflow> customTailCallWorkflow = Workflow::Get("core.function.baseAnalysis")->Clone("CustomTailCallWorkflow");
 		customTailCallWorkflow->RegisterActivity(new Activity("extension.translateTailCalls", &TailCallTranslation));
 		customTailCallWorkflow->Replace("core.function.translateTailCalls", "extension.translateTailCalls");
 		customTailCallWorkflow->Remove("core.function.translateTailCalls");

examples/workflows/unflatten/library.cpp

@@ -411,7 +411,7 @@ extern "C"
 
 	BINARYNINJAPLUGIN bool CorePluginInit()
 	{
-		auto wf = Workflow::Instance("core.function.metaAnalysis")->Clone("core.function.metaAnalysis");
+		auto wf = Workflow::Get("core.function.metaAnalysis")->Clone("core.function.metaAnalysis");
 		wf->RegisterActivity(new Activity(R"~(
 				{
 					"name": "extension.unflatten_limoncello_cpp.unflatten.dry_run",

plugins/efi_resolver/src/Plugin.cpp

@@ -61,7 +61,7 @@ extern "C"
 	BINARYNINJAPLUGIN bool CorePluginInit()
 	{
 		EfiGuidRenderer::Register();
-		auto workflow = Workflow::Instance("core.module.metaAnalysis")->Clone();
+		auto workflow = Workflow::Get("core.module.metaAnalysis")->Clone();
 		workflow->RegisterActivity(R"~({
 			"title": "EFI Resolver",
 			"name": "analysis.efi.efiResolver",

plugins/rtti/plugin.cpp

@@ -91,7 +91,7 @@ extern "C" {
 		// TODO:	2. Identify if the function is unique to a class, renaming and retyping if true
 		// TODO:	3. Identify functions which address a VFT and are probably a constructor (alloc use), retyping if true
 		// TODO:	4. Identify functions which address a VFT and are probably a deconstructor (free use), retyping if true
-		Ref<Workflow> rttiMetaWorkflow = Workflow::Instance("core.module.metaAnalysis")->Clone();
+		Ref<Workflow> rttiMetaWorkflow = Workflow::Get("core.module.metaAnalysis")->Clone();
 
 		// Add RTTI analysis.
 		rttiMetaWorkflow->RegisterActivity(R"~({

plugins/workflow_objc/Workflow.cpp

@@ -307,7 +307,7 @@ static constexpr auto WorkflowInfo = R"({
 
 void Workflow::registerActivities()
 {
-    const auto wf = BinaryNinja::Workflow::Instance("core.function.baseAnalysis")->Clone("core.function.objectiveC");
+    const auto wf = BinaryNinja::Workflow::Get("core.function.baseAnalysis")->Clone("core.function.objectiveC");
     wf->RegisterActivity(new BinaryNinja::Activity(
         ActivityID::ResolveMethodCalls, &Workflow::inlineMethodCalls));
     wf->InsertAfter("core.function.translateTailCalls", ActivityID::ResolveMethodCalls);

python/workflow.py

@@ -288,7 +288,7 @@ def __iter__(self):
 
 	def __getitem__(self, value):
 		binaryninja._init_plugins()
-		workflow = core.BNWorkflowInstance(str(value))
+		workflow = core.BNWorkflowGetOrCreate(str(value))
 		return Workflow(handle=workflow)
 
 
@@ -344,7 +344,7 @@ class Workflow(metaclass=_WorkflowMetaclass):
 	def __init__(self, name: str = "", handle: core.BNWorkflowHandle = None, query_registry: bool = True, object_handle: Union[core.BNFunctionHandle, core.BNBinaryViewHandle] = None):
 		if handle is None:
 			if query_registry:
-				_handle = core.BNWorkflowInstance(str(name))
+				_handle = core.BNWorkflowGetOrCreate(str(name))
 			else:
 				_handle = core.BNCreateWorkflow(name)
 		else:

rust/src/workflow.rs

@@ -204,9 +204,8 @@ impl Workflow {
 
     /// Get an existing [Workflow] by name.
     pub fn get(name: &str) -> Option<Ref<Workflow>> {
-        // TODO: BNWorkflowInstance has get-or-create semantics. There is currently no way to just get.
         let name = name.to_cstr();
-        let result = unsafe { BNWorkflowInstance(name.as_ptr()) };
+        let result = unsafe { BNWorkflowGet(name.as_ptr()) };
         let handle = NonNull::new(result)?;
         Some(unsafe { Workflow::ref_from_raw(handle) })
     }