docs/sources/mono-api-embedding.html

   1 <h2>Embedding Mono</h2>
   2
   3         <p>The Mono runtime can be embedded into C and C++
   4         applications.   Your C/C++ code can invoke managed code
   5         running in the Mono/.NET world and you can also surface your
   6         internal application APIs to Mono and .NET.
   7
   8         <p>For an overview of how to embed Mono into your application
   9         and the strategies that you can use to embed Mono, check the
  10         Mono
  11         website's <a href="http://www.mono-project.com/docs/advanced/embedding/">Embedding
  12         Mono</a> page.
  13
  14         <p>This page is the companion API reference for the above guide.
  15
  16         <p>The simplest way of embedding Mono is illustrated here:
  17 <pre>
  18 int main (int argc, char *argv)
  19 {
  20         /*
  21          * Load the default Mono configuration file, this is needed
  22          * if you are planning on using the dllmaps defined on the
  23          * system configuration
  24          */
  25         mono_config_parse (NULL);
  26
  27         /*
  28          * mono_jit_init() creates a domain: each assembly is
  29          * loaded and run in a MonoDomain.
  30          */
  31         MonoDomain *domain = mono_jit_init ("startup.exe");
  32
  33         /*
  34          * Optionally, add an internal call that your startup.exe
  35          * code can call, this will bridge startup.exe to Mono
  36          */
  37         mono_add_internal_call ("Sample::GetMessage", getMessage);
  38
  39         /*
  40          * Open the executable, and run the Main method declared
  41          * in the executable
  42          */
  43         MonoAssembly *assembly = mono_domain_assembly_open (domain, "startup.exe");
  44
  45         if (!assembly)
  46                 exit (2);
  47         /*
  48          * mono_jit_exec() will run the Main() method in the assembly.
  49          * The return value needs to be looked up from
  50          * System.Environment.ExitCode.
  51          */
  52         mono_jit_exec (domain, assembly, argc, argv);
  53 }
  54
  55 /* The C# signature for this method is: string GetMessage () in class Sample */
  56 MonoString*
  57 getMessage ()
  58 {
  59         return mono_string_new (mono_domain_get (), "Hello, world");
  60 }
  61 </pre>
  62
  63 <h4><a name="api:mono_jit_init">mono_jit_init</a></h4>
  64 <h4><a name="api:mono_jit_parse_options">mono_jit_parse_options</a></h4>
  65 <h4><a name="api:mono_jit_exec">mono_jit_exec</a></h4>
  66 <h4><a name="api:mono_set_dirs">mono_set_dirs</a></h4>
  67 <h4><a name="api:mono_parse_default_optimizations">mono_parse_default_optimizations</a></h4>
  68 <h4><a name="api:mono_runtime_set_main_args">mono_runtime_set_main_args</a></h4>
  69 <h4><a name="api:mono_jit_cleanup">mono_jit_cleanup</a></h4>
  70 <h4><a name="api:mono_jit_set_trace_options">mono_jit_set_trace_options</a></h4>
  71
  72
  73 <h3>Internal Calls</h3>
  74
  75         <p>The Mono runtime provides two mechanisms to expose C code
  76         to the CIL universe: internal calls and native C
  77         code. Internal calls are tightly integrated with the runtime,
  78         and have the least overhead, as they use the same data types
  79         that the runtime uses.
  80
  81         <p>The other option is to use the Platform Invoke (P/Invoke)
  82         to call C code from the CIL universe, using the standard
  83         <a href="http://www.mono-project.com/Interop_with_Native_Libraries">P/Invoke</a>
  84         mechanisms.
  85
  86         <p>To register an internal call, use this call you use the
  87         <a href="#api:mono_add_internal_call"><tt>mono_add_internal_call</tt>
  88         routine.
  89
  90 <h4><a name="api:mono_add_internal_call">mono_add_internal_call</a></h4>
  91
  92 <h3>P/Invoke with embedded applications</h3>
  93
  94         <p>Unlike internal calls, Platform/Invoke is easier to use and
  95         more portable.  It allows you to share code with Windows and
  96         .NET that have a different setup for internal calls to their
  97         own runtime.
  98
  99         <p>Usually P/Invoke declarations reference external libraries
 100         like:
 101
 102         <pre>
 103         [DllImport ("opengl")]
 104         void glBegin (GLEnum mode)
 105         </pre>
 106
 107         <p>Mono extends P/Invoke to support looking up symbols not in
 108         an external library, but looking up those symbols into the
 109         same address space as your program, to do this, use the
 110         special library name "__Internal".   This will direct Mono to
 111         lookup the method in your own process.
 112
 113         <p>There are situations where the host operating system does
 114         not support looking up symbols on the process address space.
 115         For situations like this you can use
 116         the <a href="#api:mono_dl_register_library">mono_dl_register_library</a>.
 117
 118 <h4><a name="api:mono_dl_register_library">mono_dl_register_library</h4>
 119
 120 <h3>Data Marshalling</h3>
 121
 122         <p>Managed objects are represented as <tt>MonoObject*</tt>
 123         types.  Those objects that the runtime consumes directly have
 124         more specific C definitions (for example strings are of type
 125         <tt>MonoString *</tt>, delegates are of type
 126         <tt>MonoDelegate*</tt> but they are still <tt>MonoObject
 127         *</tt>s).
 128
 129         <p>As of Mono 1.2.x types defined in mscorlib.dll do not have
 130         their fields reordered in any way.   But other libraries might
 131         have their fields reordered.   In these cases, Managed
 132         structures and objects have the same layout in the C# code as
 133         they do in the unmanaged world.
 134
 135         <p>Structures defined outside corlib must have a specific
 136         StructLayout definition, and have it set as sequential if you
 137         plan on accessing these fields directly from C code.
 138
 139         <p><b>Important</B> Internal calls do not provide support for
 140         marshalling structures.  This means that any API calls that
 141         take a structure (excluding the system types like int32,
 142         int64, etc) must be passed as a pointer, in C# this means
 143         passing the value as a "ref" or "out" parameter.
 144
 145 <h3>Mono Runtime Configuration</h3>
 146
 147         <p>Certain features of the Mono runtime, like DLL mapping, are
 148         available through a configuration file that is loaded at
 149         runtime.   The default Mono implementation loads the
 150         configuration file from <tt>$sysconfig/mono/config</tt>
 151         (typically this is <tt>/etc/mono/config</tt>).
 152
 153         <p>See the <tt>mono-config(5)</tt> man page for more details
 154         on what goes in this file.
 155
 156         <p>The following APIs expose this functionality:
 157
 158 <h4><a name="api:mono_config_cleanup">mono_config_cleanup</a></h4>
 159 <h4><a name="api:mono_config_is_server_mode">mono_config_is_server_mode</a></h4>
 160 <h4><a name="api:mono_config_parse">mono_config_parse</a></h4>
 161 <h4><a name="api:mono_config_parse_memory">mono_config_parse_memory</a></h4>
 162 <h4><a name="api:mono_config_set_server_mode">mono_config_set_server_mode</a></h4>
 163 <h4><a name="api:mono_config_string_for_assembly_file">mono_config_string_for_assembly_file</a></h4>
 164 <h4><a name="api:mono_get_config_dir">mono_get_config_dir</a></h4>
 165 <h4><a name="api:mono_get_machine_config">mono_get_machine_config</a></h4>
 166 <h4><a name="api:mono_register_machine_config">mono_register_machine_config</a></h4>
 167 <h4><a name="api:mono_set_config_dir">mono_set_config_dir</a></h4>
 168
 169 <h3>Advanced Execution Setups</h3>
 170
 171         <p>These are not recommended ways of initializing Mono, they
 172         are done internally by mono_jit_init, but are here to explain
 173         what happens internally.
 174
 175 <h4><a name="api:mono_runtime_exec_managed_code">mono_runtime_exec_managed_code</a></h4>
 176 <h4><a name="api:mono_runtime_exec_main">mono_runtime_exec_main</a></h4>
 177 <h4><a name="api:mono_init">mono_init</a></h4>
 178 <h4><a name="api:mono_init_from_assembly">mono_init_from_assembly</a></h4>
 179 <h4><a name="api:mono_init_version">mono_init_version</a></h4>
 180 <h4><a name="api:mono_jit_exec">mono_jit_exec</a></h4>
 181 <h4><a name="api:mono_jit_set_aot_mode">mono_jit_set_aot_mode</a></h4>
 182 <h4><a name="api:mono_set_break_policy">mono_set_break_policy</a></h4>
 183 <h4><a name="api:mono_get_runtime_build_info">mono_get_runtime_build_info</a></h4>
 184
 185 <h3>Signal Chaining</h3>
 186
 187 <h4><a name="api:mono_set_signal_chaining">mono_set_signal_chaining</a></h4>
 188 <h4><a name="api:mono_set_crash_chaining">mono_set_crash_chaining</a></h4>