Hide IPC proxy internal mappings by generalzing the binding call in the IPC and delegating its actual execution to the outer hosting code

Author: sgretscher

IPC/ARAIPC.h

@@ -193,6 +193,17 @@ typedef struct ARAIPCMessageSender
 //! @}
 
 
+//! Companion API: opaque encapsulation
+//! @{
+//! to keep the IPC decoupled from the Companion API in use, the IPC code uses an opaque token to represent a plug-in instance
+typedef size_t ARAIPCPlugInInstanceRef;
+
+//! callback that the proxy uses to execute the binding of an opaque Companion API plug-in instance to the given document controller
+typedef const ARAPlugInExtensionInstance* (*ARAIPCBindingHandler) (ARAIPCPlugInInstanceRef plugInInstanceRef,
+                    ARADocumentControllerRef controllerRef, ARAPlugInInstanceRoleFlags knownRoles, ARAPlugInInstanceRoleFlags assignedRoles);
+//! @}
+
+
 #if defined(__cplusplus)
 }   // extern "C"
 }   // namespace IPC

IPC/ARAIPCEncoding.h

@@ -978,6 +978,7 @@ constexpr ARAIPCMessageID _encodeMessageID ()
 constexpr ARAIPCMessageID kGetFactoriesCountMessageID { 1 };
 constexpr ARAIPCMessageID kGetFactoryMessageID { 2 };
 constexpr ARAIPCMessageID kCreateDocumentControllerMessageID { 3 };
+constexpr ARAIPCMessageID kBindToDocumentControllerMessageID { 4 };
 
 
 // caller side: create a message with the specified arguments

IPC/ARAIPCProxyHost.cpp

@@ -585,6 +585,7 @@ using namespace ProxyHost;
 
 std::vector<const ARAFactory*> _factories {};
 ARAIPCMessageSender _plugInCallbacksSender {};
+ARAIPCBindingHandler _bindingHandler {};
 
 void ARAIPCProxyHostAddFactory (const ARAFactory* factory)
 {
@@ -599,19 +600,14 @@ void ARAIPCProxyHostSetPlugInCallbacksSender (ARAIPCMessageSender plugInCallback
     _plugInCallbacksSender = plugInCallbacksSender;
 }
 
-ARADocumentControllerRef ARAIPCProxyHostTranslateDocumentControllerRef (ARADocumentControllerRef remoteRef)
+void ARAIPCProxyHostSetBindingHandler(ARAIPCBindingHandler handler)
 {
-    return fromRef (remoteRef)->getRef ();
+    _bindingHandler = handler;
 }
 
-ARAPlugInExtensionRef ARAIPCProxyHostCreatePlugInExtension (const ARAPlugInExtensionInstance* instance)
+void ARAIPCProxyHostCleanupBinding (const ARA::ARAPlugInExtensionInstance* plugInExtensionInstance)
 {
-    return toRef (new PlugInExtension { instance });
-}
-
-void ARAIPCProxyHostDestroyPlugInExtension (ARAPlugInExtensionRef plugInExtensionRef)
-{
-    delete fromRef (plugInExtensionRef);
+    delete fromRef (plugInExtensionInstance->plugInExtensionRef);
 }
 
 void ARAIPCProxyHostCommandHandler (const ARAIPCMessageID messageID, const ARAIPCMessageDecoder* const decoder, ARAIPCMessageEncoder* const replyEncoder)
@@ -677,6 +673,16 @@ void ARAIPCProxyHostCommandHandler (const ARAIPCMessageID messageID, const ARAIP
             return encodeReply (replyEncoder, ARADocumentControllerRef { toRef (documentController) });
         }
     }
+    else if (messageID == kBindToDocumentControllerMessageID)
+    {
+        ARAIPCPlugInInstanceRef plugInInstanceRef;
+        ARADocumentControllerRef controllerRef;
+        ARAPlugInInstanceRoleFlags knownRoles;
+        ARAPlugInInstanceRoleFlags assignedRoles;
+        decodeArguments (decoder, plugInInstanceRef, controllerRef, knownRoles, assignedRoles);
+        const auto plugInExtensionInstance { _bindingHandler (plugInInstanceRef, fromRef (controllerRef)->getRef (), knownRoles, assignedRoles) };
+        return encodeReply (replyEncoder, ARAPlugInExtensionRef { toRef (new PlugInExtension { plugInExtensionInstance })});
+    }
 
     //ARADocumentControllerInterface
     else if (messageID == ARA_IPC_PLUGIN_METHOD_ID (ARADocumentControllerInterface, destroyDocumentController))

IPC/ARAIPCProxyHost.h

@@ -19,11 +19,10 @@
 #ifndef ARAIPCProxyHost_h
 #define ARAIPCProxyHost_h
 
-
 #include "ARA_Library/IPC/ARAIPC.h"
 
-#if ARA_ENABLE_IPC
 
+#if ARA_ENABLE_IPC
 
 #if defined(__cplusplus)
 namespace ARA {
@@ -38,15 +37,14 @@ void ARAIPCProxyHostAddFactory(const ARAFactory * factory);
 //! static configuration: set sender that the proxy host will use to perform callbacks received from the plug-in
 void ARAIPCProxyHostSetPlugInCallbacksSender(ARAIPCMessageSender plugInCallbacksSender);
 
+//! static configuration: set the callback to execute the binding of Companion API plug-in instances to ARA document controllers
+void ARAIPCProxyHostSetBindingHandler(ARAIPCBindingHandler handler);
+
 //! static dispatcher: the host command handler that controls the proxy host
 void ARAIPCProxyHostCommandHandler(const ARAIPCMessageID messageID, const ARAIPCMessageDecoder * decoder, ARAIPCMessageEncoder * replyEncoder);
 
-//! translation needed when establishing the binding to the remote documentController
-ARADocumentControllerRef ARAIPCProxyHostTranslateDocumentControllerRef(ARADocumentControllerRef remoteRef);
-
-//! creating and deleting plug-in extension instances associated with the proxy host
-ARAPlugInExtensionRef ARAIPCProxyHostCreatePlugInExtension(const ARAPlugInExtensionInstance * instance);
-void ARAIPCProxyHostDestroyPlugInExtension(ARAPlugInExtensionRef plugInExtensionRef);
+//! trigger proper teardown of proxy plug-in extension when destroying Companion API plug-in instances that have been bound to ARA
+void ARAIPCProxyHostCleanupBinding(const ARAPlugInExtensionInstance * plugInExtensionInstance);
 
 
 #if defined(__cplusplus)
@@ -55,7 +53,6 @@ void ARAIPCProxyHostDestroyPlugInExtension(ARAPlugInExtensionRef plugInExtension
 }   // namespace ARA
 #endif
 
-
 #endif // ARA_ENABLE_IPC
 
 #endif // ARAIPCProxyHost_h

IPC/ARAIPCProxyPlugIn.cpp

@@ -1304,18 +1304,22 @@ const ARADocumentControllerInstance* ARAIPCProxyPlugInCreateDocumentControllerWi
     return result->getInstance ();
 }
 
-ARADocumentControllerRef ARAIPCProxyPlugInTranslateDocumentControllerRef (ARADocumentControllerRef documentControllerRef)
-{
-    return static_cast<DocumentController*> (PlugIn::fromRef (documentControllerRef))->getRemoteRef ();
-}
-
-const ARAPlugInExtensionInstance* ARAIPCProxyPlugInCreatePlugInExtension (size_t remoteExtensionRef, ARAIPCMessageSender sender, ARADocumentControllerRef documentControllerRef,
+const ARAPlugInExtensionInstance* ARAIPCProxyPlugInBindToDocumentController (ARAIPCPlugInInstanceRef remoteRef, ARAIPCMessageSender sender, ARADocumentControllerRef documentControllerRef,
                                                                             ARAPlugInInstanceRoleFlags knownRoles, ARAPlugInInstanceRoleFlags assignedRoles)
 {
+    const auto remoteDocumentControllerRef { static_cast<DocumentController*> (PlugIn::fromRef (documentControllerRef))->getRemoteRef () };
+
+    size_t remoteExtensionRef {};
+    RemoteCaller::CustomDecodeFunction customDecode { [&remoteExtensionRef] (const ARAIPCMessageDecoder& decoder) -> void
+        {
+            decoder.methods->readSize (decoder.ref, 0, &remoteExtensionRef);
+        } };
+    RemoteCaller { sender }.remoteCallWithReply (customDecode, false, kBindToDocumentControllerMessageID, remoteRef, remoteDocumentControllerRef, knownRoles, assignedRoles);
+
     return new PlugInExtension { sender, documentControllerRef, knownRoles, assignedRoles, remoteExtensionRef };
 }
 
-void ARAIPCProxyPlugInDestroyPlugInExtension (const ARAPlugInExtensionInstance* plugInExtensionInstance)
+void ARAIPCProxyPlugInCleanupBinding (const ARAPlugInExtensionInstance* plugInExtensionInstance)
 {
     delete static_cast<const PlugInExtension*> (plugInExtensionInstance);
 }

IPC/ARAIPCProxyPlugIn.h

@@ -48,14 +48,13 @@ const ARADocumentControllerInstance * ARAIPCProxyPlugInCreateDocumentControllerW
 //! static handler of received messages
 void ARAIPCProxyPlugInCallbacksDispatcher(const ARAIPCMessageID messageID, const ARAIPCMessageDecoder * decoder, ARAIPCMessageEncoder *  replyEncoder);
 
-//! \todo to perform the binding to the remote plug-in instance, the host needs access to this translation...
-ARADocumentControllerRef ARAIPCProxyPlugInTranslateDocumentControllerRef(ARADocumentControllerRef documentControllerRef);
-
-//! create the plug-in extension when performing the binding to the remote plug-in instance
-const ARAPlugInExtensionInstance * ARAIPCProxyPlugInCreatePlugInExtension(size_t remoteExtensionRef, ARAIPCMessageSender sender, ARADocumentControllerRef documentControllerRef,
-                                                                          ARAPlugInInstanceRoleFlags knownRoles, ARAPlugInInstanceRoleFlags assignedRoles);
-//! destroy the plug-in extension when destroying the remote plug-in instance
-void ARAIPCProxyPlugInDestroyPlugInExtension(const ARAPlugInExtensionInstance * plugInExtension);
+//! create the proxy plug-in extension when performing the binding to the remote plug-in instance
+const ARAPlugInExtensionInstance * ARAIPCProxyPlugInBindToDocumentController(ARAIPCPlugInInstanceRef remoteRef,
+                                                                            ARAIPCMessageSender sender, ARADocumentControllerRef documentControllerRef,
+                                                                            ARAPlugInInstanceRoleFlags knownRoles, ARAPlugInInstanceRoleFlags assignedRoles);
+
+//! trigger proper teardown of proxy plug-in extension upon destroying a remote plug-in instance that has been bound to ARA
+void ARAIPCProxyPlugInCleanupBinding(const ARAPlugInExtensionInstance * plugInExtension);
 
 
 #if defined(__cplusplus)