netcore/corerun/coreclrhost.h

   1 // Licensed to the .NET Foundation under one or more agreements.
   2 // The .NET Foundation licenses this file to you under the MIT license.
   3 // See the LICENSE file in the project root for more information.
   4
   5 //
   6 // APIs for hosting CoreCLR
   7 //
   8
   9 #ifndef __CORECLR_HOST_H__
  10 #define __CORECLR_HOST_H__
  11
  12 #if defined(_WIN32) && defined(_M_IX86)
  13 #define CORECLR_CALLING_CONVENTION __stdcall
  14 #else
  15 #define CORECLR_CALLING_CONVENTION
  16 #endif
  17
  18 // For each hosting API, we define a function prototype and a function pointer
  19 // The prototype is useful for implicit linking against the dynamic coreclr
  20 // library and the pointer for explicit dynamic loading (dlopen, LoadLibrary)
  21 #define CORECLR_HOSTING_API(function, ...) \
  22     extern "C" int CORECLR_CALLING_CONVENTION function(__VA_ARGS__); \
  23     typedef int (CORECLR_CALLING_CONVENTION *function##_ptr)(__VA_ARGS__)
  24
  25 //
  26 // Initialize the CoreCLR. Creates and starts CoreCLR host and creates an app domain
  27 //
  28 // Parameters:
  29 //  exePath                 - Absolute path of the executable that invoked the ExecuteAssembly (the native host application)
  30 //  appDomainFriendlyName   - Friendly name of the app domain that will be created to execute the assembly
  31 //  propertyCount           - Number of properties (elements of the following two arguments)
  32 //  propertyKeys            - Keys of properties of the app domain
  33 //  propertyValues          - Values of properties of the app domain
  34 //  hostHandle              - Output parameter, handle of the created host
  35 //  domainId                - Output parameter, id of the created app domain
  36 //
  37 // Returns:
  38 //  HRESULT indicating status of the operation. S_OK if the assembly was successfully executed
  39 //
  40 CORECLR_HOSTING_API(coreclr_initialize,
  41             const char* exePath,
  42             const char* appDomainFriendlyName,
  43             int propertyCount,
  44             const char** propertyKeys,
  45             const char** propertyValues,
  46             void** hostHandle,
  47             unsigned int* domainId);
  48
  49 //
  50 // Shutdown CoreCLR. It unloads the app domain and stops the CoreCLR host.
  51 //
  52 // Parameters:
  53 //  hostHandle              - Handle of the host
  54 //  domainId                - Id of the domain
  55 //
  56 // Returns:
  57 //  HRESULT indicating status of the operation. S_OK if the assembly was successfully executed
  58 //
  59 CORECLR_HOSTING_API(coreclr_shutdown,
  60             void* hostHandle,
  61             unsigned int domainId);
  62
  63 //
  64 // Shutdown CoreCLR. It unloads the app domain and stops the CoreCLR host.
  65 //
  66 // Parameters:
  67 //  hostHandle              - Handle of the host
  68 //  domainId                - Id of the domain
  69 //  latchedExitCode         - Latched exit code after domain unloaded
  70 //
  71 // Returns:
  72 //  HRESULT indicating status of the operation. S_OK if the assembly was successfully executed
  73 //
  74 CORECLR_HOSTING_API(coreclr_shutdown_2,
  75             void* hostHandle,
  76             unsigned int domainId,
  77             int* latchedExitCode);
  78
  79 //
  80 // Create a native callable function pointer for a managed method.
  81 //
  82 // Parameters:
  83 //  hostHandle              - Handle of the host
  84 //  domainId                - Id of the domain
  85 //  entryPointAssemblyName  - Name of the assembly which holds the custom entry point
  86 //  entryPointTypeName      - Name of the type which holds the custom entry point
  87 //  entryPointMethodName    - Name of the method which is the custom entry point
  88 //  delegate                - Output parameter, the function stores a native callable function pointer to the delegate at the specified address
  89 //
  90 // Returns:
  91 //  HRESULT indicating status of the operation. S_OK if the assembly was successfully executed
  92 //
  93 CORECLR_HOSTING_API(coreclr_create_delegate,
  94             void* hostHandle,
  95             unsigned int domainId,
  96             const char* entryPointAssemblyName,
  97             const char* entryPointTypeName,
  98             const char* entryPointMethodName,
  99             void** delegate);
 100
 101 //
 102 // Execute a managed assembly with given arguments
 103 //
 104 // Parameters:
 105 //  hostHandle              - Handle of the host
 106 //  domainId                - Id of the domain
 107 //  argc                    - Number of arguments passed to the executed assembly
 108 //  argv                    - Array of arguments passed to the executed assembly
 109 //  managedAssemblyPath     - Path of the managed assembly to execute (or NULL if using a custom entrypoint).
 110 //  exitCode                - Exit code returned by the executed assembly
 111 //
 112 // Returns:
 113 //  HRESULT indicating status of the operation. S_OK if the assembly was successfully executed
 114 //
 115 CORECLR_HOSTING_API(coreclr_execute_assembly,
 116             void* hostHandle,
 117             unsigned int domainId,
 118             int argc,
 119             const char** argv,
 120             const char* managedAssemblyPath,
 121             unsigned int* exitCode);
 122
 123 #undef CORECLR_HOSTING_API
 124
 125 #endif // __CORECLR_HOST_H__