Merge pull request #22801 from janvorli/improve-coreclrhost-header

Improve coreclrhost.h header

1 files changed, 72 insertions, 2 deletions

diff --git a/src/coreclr/hosts/inc/coreclrhost.h b/src/coreclr/hosts/inc/coreclrhost.h
index dd11cb6a51..d1ec724974 100644
--- a/src/coreclr/hosts/inc/coreclrhost.h
+++ b/src/coreclr/hosts/inc/coreclrhost.h
@@ -9,13 +9,34 @@
 #ifndef __CORECLR_HOST_H__
 #define __CORECLR_HOST_H__
 
+#if defined(_WIN32) && defined(_M_IX86)
+#define CORECLR_CALLING_CONVENTION __stdcall
+#else
+#define CORECLR_CALLING_CONVENTION
+#endif
+
 // For each hosting API, we define a function prototype and a function pointer
 // The prototype is useful for implicit linking against the dynamic coreclr
 // library and the pointer for explicit dynamic loading (dlopen, LoadLibrary)
 #define CORECLR_HOSTING_API(function, ...) \
-    extern "C" int function(__VA_ARGS__); \
-    typedef int (*function##_ptr)(__VA_ARGS__)
+    extern "C" int CORECLR_CALLING_CONVENTION function(__VA_ARGS__); \
+    typedef int (CORECLR_CALLING_CONVENTION *function##_ptr)(__VA_ARGS__)
     
+//
+// Initialize the CoreCLR. Creates and starts CoreCLR host and creates an app domain
+//
+// Parameters:
+//  exePath                 - Absolute path of the executable that invoked the ExecuteAssembly (the native host application)
+//  appDomainFriendlyName   - Friendly name of the app domain that will be created to execute the assembly
+//  propertyCount           - Number of properties (elements of the following two arguments)
+//  propertyKeys            - Keys of properties of the app domain
+//  propertyValues          - Values of properties of the app domain
+//  hostHandle              - Output parameter, handle of the created host
+//  domainId                - Output parameter, id of the created app domain 
+//
+// Returns:
+//  HRESULT indicating status of the operation. S_OK if the assembly was successfully executed
+//
 CORECLR_HOSTING_API(coreclr_initialize,
             const char* exePath,
             const char* appDomainFriendlyName,
@@ -25,15 +46,50 @@ CORECLR_HOSTING_API(coreclr_initialize,
             void** hostHandle,
             unsigned int* domainId);
 
+//
+// Shutdown CoreCLR. It unloads the app domain and stops the CoreCLR host.
+//
+// Parameters:
+//  hostHandle              - Handle of the host
+//  domainId                - Id of the domain
+//
+// Returns:
+//  HRESULT indicating status of the operation. S_OK if the assembly was successfully executed
+//
 CORECLR_HOSTING_API(coreclr_shutdown,
             void* hostHandle,
             unsigned int domainId);
 
+//
+// Shutdown CoreCLR. It unloads the app domain and stops the CoreCLR host.
+//
+// Parameters:
+//  hostHandle              - Handle of the host
+//  domainId                - Id of the domain
+//  latchedExitCode         - Latched exit code after domain unloaded
+//
+// Returns:
+//  HRESULT indicating status of the operation. S_OK if the assembly was successfully executed
+//
 CORECLR_HOSTING_API(coreclr_shutdown_2,
             void* hostHandle,
             unsigned int domainId,
             int* latchedExitCode);
 
+//
+// Create a native callable function pointer for a managed method.
+//
+// Parameters:
+//  hostHandle              - Handle of the host
+//  domainId                - Id of the domain 
+//  entryPointAssemblyName  - Name of the assembly which holds the custom entry point
+//  entryPointTypeName      - Name of the type which holds the custom entry point
+//  entryPointMethodName    - Name of the method which is the custom entry point
+//  delegate                - Output parameter, the function stores a native callable function pointer to the delegate at the specified address
+//
+// Returns:
+//  HRESULT indicating status of the operation. S_OK if the assembly was successfully executed
+//
 CORECLR_HOSTING_API(coreclr_create_delegate,
             void* hostHandle,
             unsigned int domainId,
@@ -42,6 +98,20 @@ CORECLR_HOSTING_API(coreclr_create_delegate,
             const char* entryPointMethodName,
             void** delegate);
 
+//
+// Execute a managed assembly with given arguments
+//
+// Parameters:
+//  hostHandle              - Handle of the host
+//  domainId                - Id of the domain 
+//  argc                    - Number of arguments passed to the executed assembly
+//  argv                    - Array of arguments passed to the executed assembly
+//  managedAssemblyPath     - Path of the managed assembly to execute (or NULL if using a custom entrypoint).
+//  exitCode                - Exit code returned by the executed assembly
+//
+// Returns:
+//  HRESULT indicating status of the operation. S_OK if the assembly was successfully executed
+//
 CORECLR_HOSTING_API(coreclr_execute_assembly,
             void* hostHandle,
             unsigned int domainId,